Data Workflow Ingest Status Lookup

What this endpoint does

Reads the processing lifecycle for an asynchronously ingested Data Workflow batch. Use the trigger_id and client-provided metadata.batch_id to check whether the batch is pending, queued, processing, processed, skipped, orphaned, or failed.

This endpoint only reads the persisted event_ingest status. It does not submit or queue an ingest request, wait for workflow execution, or return row-level results. A successful ingest submission means the request was accepted for asynchronous processing; it does not mean processing has completed.

INFO

Workflow

Submit an ingest request with trigger_id and metadata.batch_id → receive queue acceptance → call GET /apis/v1/data-workflows/event-ingests/status with the same trigger_id and batch_id → poll until the status is terminal → inspect error and counts.

Quick start

Authentication and permission

Send Authorization: Bearer <COMMUNITY_API_KEY>. The community API key must belong to the community that owns the Data Workflow trigger and include the dataWorkflows permission. Keep the key server-side.

The lookup is scoped to the authenticated key's community, so a key cannot read another community's ingest status.

Request

Method: GET
Path: /apis/v1/data-workflows/event-ingests/status

Query parameter	Type	Required	Description
`trigger_id`	string	Yes	A 24-character hexadecimal Data Workflow event-ingest trigger ObjectId.
`batch_id`	string	Yes	The client batch ID supplied in the ingest payload as `metadata.batch_id`. It must contain at least one non-whitespace character.

Success response

HTTP 200. The response describes the persisted batch lifecycle record. Missing historical count values are returned as 0; missing timestamps are returned as null.

{
  "trigger_id": "6a43d5141d4be4089b58e2e7",
  "batch_id": "batch-2026-07-01-040",
  "status": "processed",
  "received_at": "2026-07-01T01:28:35.000Z",
  "processed_at": "2026-07-01T01:58:42.000Z",
  "accepted_record_count": 1,
  "skipped_record_count": 0,
  "error": null
}

Property	Type	Description
`trigger_id`	string	The trigger ID used for the lookup.
`batch_id`	string	The client-provided batch ID used for the lookup.
`status`	string	Current persisted lifecycle status: `pending`, `queued`, `processing`, `processed`, `skipped`, `orphaned`, or `failed`. Internal `normalized` records are returned as `processed`.
`received_at`	string \| null	ISO 8601 time when the ingest was first durably persisted.
`processed_at`	string \| null	ISO 8601 time when processing completed, when available.
`accepted_record_count`	number	Number of accepted records, or `0` when the stored row has no count.
`skipped_record_count`	number	Number of skipped records, or `0` when the stored row has no count.
`error`	object \| null	`null` when no stored failure or skip reason is available. Otherwise includes a stable `code` and stored `message`.

Failed and orphaned records return an error such as:

{
  "code": "INGEST_FAILED",
  "message": "Record idempotency requires a JSON data[] row payload."
}

Skipped records with a stored skip reason return code: "INGEST_SKIPPED" and the reason in message.

Errors and recovery

Status	Code	When	Recovery
`400`	`INVALID_TRIGGER_ID`	`trigger_id` is missing, malformed, or not a string.	Send the trigger's 24-character hexadecimal ObjectId.
`400`	`MISSING_BATCH_ID`	`batch_id` is missing, blank, or not a string.	Send the same non-empty `metadata.batch_id` used when submitting the ingest.
`401`	`AUTHENTICATION_REQUIRED`	The community API key is missing or invalid.	Send a valid community API key in the `Authorization` header.
`401`	—	The community API key is missing the required permission.	Use a key for the trigger's community with the `dataWorkflows` permission.
`401`	`COMMUNITY_CONTEXT_MISSING`	Authentication did not provide a valid community context.	Use a valid community API key and retry.
`404`	`EVENT_INGEST_NOT_FOUND`	No persisted status record matches this community, trigger, and batch.	Verify both IDs. A just-accepted request may not have been persisted yet; retry after a short delay.
`500`	`EVENT_INGEST_STATUS_LOOKUP_FAILED`	The service could not read the status record.	Retry with bounded backoff; contact support if the error persists.

Error response example:

{
  "code": "EVENT_INGEST_NOT_FOUND",
  "message": "No event ingest was found for the supplied trigger_id and batch_id."
}

Retry safety and gotchas

This is a read-only GET; retry timeouts with bounded backoff. Repeating the lookup does not enqueue another ingest.

batch_id is matched to the request-level batch idempotency record. A repeated duplicate batch can resolve to its skipped audit record.

There may be a short delay between queue acceptance and persistence of the event_ingest record. During that gap, lookup returns 404; retry after a short delay.

Status is the ingest lifecycle, not proof that every downstream workflow action succeeded.

This endpoint returns batch summary fields only. It does not return payload rows or row-level errors.

Read event-ingest lifecycle status by trigger and batch ID.

Data Workflow Ingest Status Lookup

What this endpoint does

Quick start

Authentication and permission

Request

Success response

Errors and recovery

Retry safety and gotchas

Request

Responses

Read event-ingest lifecycle status by trigger and batch ID.

Data Workflow Ingest Status Lookup#

What this endpoint does#

Quick start#

Authentication and permission#

Request#

Success response#

Errors and recovery#

Retry safety and gotchas#

Request

Responses

Data Workflow Ingest Status Lookup

What this endpoint does

Quick start

Authentication and permission

Request

Success response

Errors and recovery

Retry safety and gotchas