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 persisted 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 /v1/data-workflows/event-ingests/status with the same trigger_id and batch_id → poll until the status is terminal → inspect data.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
Public path: /v1/data-workflows/event-ingests/status
Integration service route: /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 is a string, not an ObjectId.

Success response

HTTP 200. The response uses the standard API envelope. The batch lifecycle fields are inside data. Missing historical count values are returned as 0; missing timestamps are returned as null.

{
  "status": "success",
  "message": "Event ingest status fetched successfully",
  "data": {
    "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
`status`	string	API envelope status. `success` for a successful lookup.
`message`	string	API-level result message.
`data.trigger_id`	string	The trigger ID used for the lookup.
`data.batch_id`	string	The client-provided batch ID used for the lookup.
`data.status`	string	Current persisted lifecycle status: `pending`, `queued`, `processing`, `processed`, `skipped`, `orphaned`, or `failed`. Internal `normalized` records are returned as `processed`.
`data.received_at`	string \| null	ISO 8601 time when the ingest was first durably persisted.
`data.processed_at`	string \| null	ISO 8601 time when processing completed, when available.
`data.accepted_record_count`	number	Number of accepted records, or `0` when the stored row has no count.
`data.skipped_record_count`	number	Number of skipped records, or `0` when the stored row has no count.
`data.error`	object \| null	`null` when no stored failure or skip reason is available. Otherwise includes a stable `code` and stored `message`.

A failed or orphaned ingest can return an error inside data:

{
  "status": "success",
  "message": "Event ingest status fetched successfully",
  "data": {
    "trigger_id": "6a43d5141d4be4089b58e2e7",
    "batch_id": "batch-2026-07-01-040",
    "status": "failed",
    "received_at": "2026-07-01T01:28:35.000Z",
    "processed_at": null,
    "accepted_record_count": 0,
    "skipped_record_count": 0,
    "error": {
      "code": "INGEST_FAILED",
      "message": "Record idempotency requires a JSON data[] row payload."
    }
  }
}

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

Errors and recovery

Endpoint validation and lookup errors use { "status": "fail", "code": "...", "message": "..." }.

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 and the batch ID. A just-accepted request may not have been persisted yet; retry shortly.
`500`	`EVENT_INGEST_STATUS_LOOKUP_FAILED`	The service could not read the status record.	Retry with bounded backoff; contact support if the error persists.

Example 404 response:

{
  "status": "fail",
  "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 a client string, such as batch-2026-09-25-100; it is not an ObjectId.

For triggers configured with batchIdPath, lookup can use the deterministic batch dedupe key. For triggers without that option, the service finds metadata.batch_id (or metaData.batch_id) in event_ingest_payloads, then reads lifecycle status from the linked event_ingest row.

There may be a short delay between queue acceptance and persistence of the event_ingest and payload records. 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