List seeding runs
/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);
}# Requires inbox_insights:read permission in the target workspace.
for run in client.email.seeding.runs.list(source_email_id="em_01krdgeqcxet5s7t44vh8rt9mg"):
print(run.model_dump_json())// Requires inbox_insights:read permission in the target workspace.
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
for run, err := range client.Email.Seeding.Runs.List(ctx, bird.EmailSeedingRunsListParams{Limit: 20}) {
if err != nil {
log.Fatal(err)
}
fmt.Println(run)
}// Requires inbox_insights:read permission in the target workspace.
foreach ($bird->email->seeding->runs->list(['limit' => 25]) as $run) {
var_dump($run->getId());
}bird email seeding runs listcurl -X GET "https://us1.platform.bird.com/v1/email/inbox-insights/automatic-seeding/runs" \
-H "Authorization: Bearer $TOKEN" \
--url-query "sort=created_at" \
--url-query "order=desc" \
--url-query "limit=25" \
--url-query "include_total=false"{
"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.
Query Parameters
sortstringField to sort by. Defaults to created_at.
Possible values: created_at
orderstringSort direction. Defaults to desc, which sorts from newest to oldest or largest to smallest, depending on the selected sort field.
Possible values: asc, desc
limitintegerMaximum number of items to return per page.
starting_afterstringCursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_beforestringCursor 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_totalbooleanWhen true, the response includes a total field with the total number of items matching the request's filters across all pages.
source_kindstringMatch the original source kind.
Possible values: api, smtp, scheduled, broadcast
source_email_idstringMatch an original email. Cannot be combined with source_broadcast_id or source_kind=broadcast; either combination returns 422.
source_broadcast_idstringMatch an original broadcast. Cannot be combined with source_email_id. If source_kind is supplied, it must be broadcast; conflicting combinations return 422.
created_afterstringLimits 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_beforestringLimits 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.
statestringMatch the current derived execution state.
Possible values: pending, registering, registration_uncertain, ready, dispatching, dispatch_complete, stopped, failed
sending_domainstringMatch the exact sending domain recorded during registration.
Response Payload
dataShow child attributes
data.iddata.stateExecution 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.sourceOriginal customer source. This never identifies a generated seed copy. Scheduled means an API-scheduled email.
data.labelLabel from a trigger address, such as spring-launch in <token>+spring-launch@.... It is a display name and selects nothing.
data.source_created_atOriginal source execution time.
data.retain_untilTime after which this run is no longer available.
data.progressDelivered, 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_domainPresent after registration establishes the sending domain.
data.list_typeList type frozen at run admission.
Possible values (may grow over time): private, public, exclusive
data.engagement_profileEngagement profile frozen at run admission.
Possible values (may grow over time): all, engaging, non_engaging
data.regionsRegions frozen at run admission.
data.registration_started_atRegistration admission time.
data.registration_finished_atTime the registration response was persisted.
data.dispatch_deadlineFixed deadline for new seed admissions.
data.dispatch_finished_atTime scheduler work completed; uncertain admission or delivery may remain.
data.stop_requested_atFirst durable stop, whether requested explicitly or imposed automatically. Already granted copies may still send.
data.reasonSanitized 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.issuesCounts of sanitized terminal or uncertain copy outcomes. No seed addresses or provider error text. Counts overlap the progress buckets.
Show child attributes
data.issues.codeA reason or delivery status affecting these copies. Unrecognized persisted reasons become unavailable.
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.countdata.created_atdata.updated_atnext_cursorCursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.
prev_cursorCursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.
refresh_cursorRefresh 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.
totalTotal number of items matching the request's filters across all pages. Present only when include_total=true was passed, and omitted otherwise.
Related resources
Continue with the documentation, guides and examples for this topic.