# Read event-ingest lifecycle status by trigger and batch ID Check whether a batch of events you sent to a data workflow has been received, run, skipped or failed. - Endpoint: `GET https://api.returning.ai/v1/data-workflows/event-ingests/status` - Section: Users and data / Data workflows - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `dataWorkflows` (Shown in the dashboard as "Data Workflows") - Retries: Read-only; poll with backoff until the status is final - Guide: hand-written - Verified: live, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/data-workflows/read-event-ingest-lifecycle-status-by-trigger-and-batch-id ## When to use this - After you send a batch of trading events to a data workflow, confirm it was received and processed. - A send timed out, and you need to know whether the batch arrived before you send it again. - A batch didn't have the effect you expected, and you want the stored failure or skip reason. **Instead:** Use [Get bulk update job status](https://docs.returning.ai/api-reference/bulk-operations/get-bulk-update-job-status.md) instead to follow a CSV upload from Bulk update users from CSV. ## Authentication - Header: `Authorization: Bearer ` - Permission: `dataWorkflows` This endpoint needs `dataWorkflows`, shown in the dashboard as Data Workflows. Use a Community API key and keep it on your server. The key decides the community, so you only see batches sent to your own community's workflows. ## Behaviour You send a batch of events to a data workflow with a `trigger_id` and a `metadata.batch_id`. This endpoint reads where that batch is now. It never sends or runs anything, and it returns counts and a reason, not the rows. What each status means: - `pending`, `queued`, `processing`: the batch is saved and waiting for, or in, its workflow run. Ask again later. - `processed`: the workflow ran with the batch. This doesn't prove every step in the workflow succeeded; check the workflow's task history in the dashboard when the result matters. - `skipped`: the batch was a repeat. When your trigger has a Batch ID Path set, sending a `batch_id` again skips the whole batch; `error.message` gives the reason, such as `Duplicate batch_id received: `. - `orphaned`: the workflow wasn't deployed when the batch came up to run, so it never ran. - `failed`: the run failed. `error.message` holds the reason. After a repeated `batch_id` is skipped, this endpoint returns the latest delivery, so you see `skipped` with zero counts even though the first delivery may have been `processed`. Keep a record of the first result before you retry, and use a new `batch_id` for a corrected batch. ## Request ### Query parameters | Name | Type | Required | Description | | --- | --- | --- | --- | | `trigger_id` | `string` | Yes | The workflow's event-ingest trigger, shown as Production Trigger ID in the trigger's settings. The same `trigger_id` you sent the batch to. (24 hex characters) | | `batch_id` | `string` | Yes | The batch ID you sent in `metadata.batch_id`. Matched exactly, including capitals. (Non-empty string) | ### Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `dataWorkflows`. (`Bearer `) | ### Example request ```bash curl --request GET \ --url 'https://api.returning.ai/v1/data-workflows/event-ingests/status?trigger_id=66f000000000000000000603&batch_id=deposits-2026-09-27-001' \ --header 'Authorization: Bearer ' ``` ## Response A `200` returns the batch's state in `data`. Branch on `data.status`, never on `message`. Missing counts come back as `0` and missing times as `null`. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `status` | `string` | always | Result of the lookup. (`success`) | | `message` | `string` | always | Human-readable summary. Do not branch on it. | | `data` | `object` | always | Where the batch is now. | | `data.trigger_id` | `string` | always | The `trigger_id` you asked about. | | `data.batch_id` | `string` | always | The `batch_id` you asked about. | | `data.status` | `string` | always | Where the batch is. `processed`, `skipped`, `orphaned` and `failed` are final; see Behaviour. (`pending`, `queued`, `processing`, `processed`, `skipped`, `orphaned`, `failed`) | | `data.received_at` | `string` | always | When the batch was first saved. `null` when not recorded. | | `data.processed_at` | `string` | always | When the workflow finished with the batch. `null` until the batch is `processed`. | | `data.accepted_record_count` | `integer` | always | Rows in `data` that were accepted for the workflow. `0` when not recorded. | | `data.skipped_record_count` | `integer` | always | Rows in `data` that were skipped, such as repeats of a record already received. `0` when not recorded. | | `data.error` | `object` | always | The stored failure or skip reason, or `null` when there is none. | | `data.error.code` | `string` | - | `INGEST_FAILED` for a `failed` or `orphaned` batch, otherwise `INGEST_SKIPPED`. (`INGEST_FAILED` or `INGEST_SKIPPED`) | | `data.error.message` | `string` | - | The stored reason, such as `Duplicate batch_id received: deposits-2026-09-27-001`. Do not branch on it. | ### Example response (200) ```json { "status": "success", "message": "Event ingest status fetched successfully", "data": { "trigger_id": "66f000000000000000000603", "batch_id": "deposits-2026-09-27-001", "status": "processed", "received_at": "2026-09-27T01:28:35.000Z", "processed_at": "2026-09-27T01:33:42.000Z", "accepted_record_count": 2, "skipped_record_count": 0, "error": null } } ``` ## Errors The 400, 404 `EVENT_INGEST_NOT_FOUND` and 500 `EVENT_INGEST_STATUS_LOOKUP_FAILED` errors carry the code in `code`. Errors from the API key check carry it in `meta.code`, except a key without `dataWorkflows`, which returns `401` with only a `message`. ### Fix the request | Status | Code | What to do | | --- | --- | --- | | 401 | - | The body is `{"message": "Your api key does not have permission to access this action"}` with no code: the key lacks `dataWorkflows`, or it's a personal key. Use a Community API key and add Data Workflows in Settings > Integration > API Keys. | | 400 | `INVALID_TRIGGER_ID` | `trigger_id` is missing, sent twice, or isn't 24 hex characters. Send the workflow's Production Trigger ID once. | | 400 | `MISSING_BATCH_ID` | `batch_id` is missing, blank or sent twice. Send the `metadata.batch_id` of the batch you're checking. | | 401 | `AUTHENTICATION_REQUIRED` | The key is missing, invalid or expired. Send `Authorization: Bearer ` with a current Community API key. | ### Fix the data | Status | Code | What to do | | --- | --- | --- | | 404 | `EVENT_INGEST_NOT_FOUND` | No batch in your community matches this `trigger_id` and `batch_id`. Check both values. A batch you sent a moment ago may not be saved yet, so wait a few seconds and ask again before you send it again. | | 404 | `COMMUNITY_NOT_FOUND` | The community this key belongs to no longer exists. Contact Returning.AI support. | ### Retry with backoff | Status | Code | What to do | | --- | --- | --- | | 500 | `EVENT_INGEST_STATUS_LOOKUP_FAILED` | The status could not be read. Retry the same request with exponential backoff. | | 500 | `AUTHENTICATION_FAILED` | The key could not be checked. Retry with backoff; nothing was read. | **Retries:** This endpoint only reads, so retrying is safe and never sends the batch again. Poll with backoff, for example every few seconds and then less often, until `data.status` is `processed`, `skipped`, `orphaned` or `failed`. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry. ## Next step - [Get user field histories for a specific user](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-user-field-histories-for-a-specific-user.md): `GET /v1/communities/{communityId}/users/{userId}/user-field-histories`. Once the batch is `processed`, check what the workflow changed for a trader. - [Or check one field across traders with Get user field histories for a specific field](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-user-field-histories-for-a-specific-field.md): `GET /v1/communities/{communityId}/user-fields/{fieldIdOrName}/histories`.