Sign inGet Started

List seeding runs

GET
/v1/email/inbox-insights/automatic-seeding/runs
// Requires inbox_insights:read permission in the target workspace.
for await (const run of bird.email.seeding.runs.list({ limit: 25 })) {
  console.log(run.id, run.state);
}
响应200
{
  "data": [
    {
      "id": "esrun_01krdgeqcxet5s7t44vh8rt9mg",
      "state": "dispatch_complete",
      "source": {
        "kind": "api",
        "email_id": "em_01krdgeqcxet5s7t44vh8rt9mg"
      },
      "label": "spring-launch",
      "source_created_at": "2026-05-20T09:14:52Z",
      "retain_until": "2027-06-19T09:14:52Z",
      "progress": {
        "planned": 48,
        "admitted": 48,
        "provider_accepted": 48,
        "delivered": 46,
        "failed": 1,
        "not_sent": 0,
        "unknown": 0,
        "pending": 1
      },
      "sending_domain": "mail.example.com",
      "list_type": "private",
      "engagement_profile": "all",
      "regions": [
        "North America - US"
      ],
      "registration_started_at": "2026-05-20T09:14:55Z",
      "registration_finished_at": "2026-05-20T09:15:02Z",
      "dispatch_deadline": "2026-05-20T10:14:52Z",
      "dispatch_finished_at": "2026-05-20T09:31:10Z",
      "issues": [
        {
          "code": "bounced",
          "count": 1
        }
      ],
      "created_at": "2026-05-20T09:14:53Z",
      "updated_at": "2026-05-20T09:31:10Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

Read retained run intents and sending progress. Results may lag recent writes and are separate from Inbox Tracker placement results. Filters use retained run metadata; tag and label search is unavailable. When both creation bounds are supplied, created_before must be later than created_after; otherwise the request returns 422.

查询参数

sortstring

Field to sort by. Defaults to created_at.

Possible values: created_at

orderstring

Sort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.

Possible values: asc, desc

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

include_totalboolean

When true, the response includes a total field with the total number of items matching the request's filters across all pages.

source_kindstring

Match the original source kind.

Possible values: api, smtp, scheduled, broadcast

source_email_idstring

Match an original email. Cannot be combined with source_broadcast_id or source_kind=broadcast; either combination returns 422.

source_broadcast_idstring

Match an original broadcast. Cannot be combined with source_email_id. If source_kind is supplied, it must be broadcast; conflicting combinations return 422.

created_afterstring

Limits the response to resources created at or after this timestamp. Combine it with created_before to select a time window. Use an RFC 3339 timestamp with a timezone offset.

created_beforestring

Limits the response to resources created before this timestamp. Combine it with created_after to select a time window. Use an RFC 3339 timestamp with a timezone offset.

statestring

Match the current derived execution state.

Possible values: pending, registering, registration_uncertain, ready, dispatching, dispatch_complete, stopped, failed

sending_domainstring

Match the exact sending domain recorded during registration.

响应载荷

data
array of object
必填
显示子属性
data.id
string
必填
data.state
string
必填

Execution state, separate from delivery and inbox placement:

  • pending: the run is recorded and registration has not started.
  • registering: registration is in progress. A stop request can coexist with an in-flight registration.
  • registration_uncertain: the registration result is unknown. Registration is not automatically repeated, and uncertainty remains visible after a stop.
  • ready: registration has produced a retained seed plan; dispatch scheduling has not started.
  • dispatching: the scheduler is admitting planned copies or recovering earlier handoffs.
  • dispatch_complete: scheduler work is acknowledged. Uncertain admission and pending delivery can remain.
  • stopped: new admissions are closed by a stop request, settings or trigger changes, or the dispatch deadline. Already granted copies may still send.
  • failed: registration failed or the source control was refused. New admissions cannot proceed; retained progress describes any copies already granted. Inspect progress and stop_requested_at alongside this state. A terminal run state does not recall previously granted or queued copies.

Possible values: pending, registering, registration_uncertain, ready, dispatching, dispatch_complete, stopped, failed

data.source
object
必填

Original customer source. This never identifies a generated seed copy. Scheduled means an API-scheduled email.

显示子属性
data.source.kind
string
必填

Original source kind for this reference.

Possible values: api, smtp, scheduled

data.source.email_id
string
必填
data.label
string

Label from a trigger address, such as spring-launch in <token>+spring-launch@.... It is a display name and selects nothing.

data.source_created_at
string
必填

Original source execution time.

data.retain_until
string
必填

Time after which this run is no longer available.

data.progress
object
必填

Delivered, failed, not_sent, unknown and pending partition planned copies. Admitted and provider_accepted overlap those buckets and must not be added to them. Late outcomes can move a copy between buckets.

显示子属性
data.sending_domain
string

Present after registration establishes the sending domain.

data.list_type
string

List type frozen at run admission.

Possible values (may grow over time): private, public, exclusive

data.engagement_profile
string

Engagement profile frozen at run admission.

Possible values (may grow over time): all, engaging, non_engaging

data.regions
array of string

Regions frozen at run admission.

data.registration_started_at
string

Registration admission time.

data.registration_finished_at
string

Time the registration response was persisted.

data.dispatch_deadline
string

Fixed deadline for new seed admissions.

data.dispatch_finished_at
string

Time scheduler work completed; uncertain admission or delivery may remain.

data.stop_requested_at
string

First durable stop, whether requested explicitly or imposed automatically. Already granted copies may still send.

data.reason
string

Sanitized reason code. Unknown stored details become unavailable; provider error text is never returned.

Possible values (may grow over time): registration_rejected, allowance_exhausted, selection_unavailable, sending_domain_not_measured, vendor_outcome_unknown, invalid_registration_response, canceled_or_expired, run_stopped, settings_disabled, trigger_rotated, dispatch_deadline_exceeded, control_rejected, source_stopped, conflicting_examples, unsupported_source, mixed_recipients, invalid_trigger, seeding_unavailable, contact_template_unsupported, source_not_authorized, content_blocked, capture_expired, capture_failed, preparation_unavailable, policy_refused, unavailable, bounced, rejected, blocked, canceled, provider_outcome_unknown, admission_uncertain, admission_refused

data.issues
array of object
必填

Counts of sanitized terminal or uncertain copy outcomes. No seed addresses or provider error text. Counts overlap the progress buckets.

显示子属性
data.created_at
string
必填
data.updated_at
string
必填
next_cursor
nullable string
必填

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
必填

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
必填

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

total
nullable integer

Total number of items matching the request's filters across all pages. Present only when include_total=true was passed, and omitted otherwise.