Returning.AIDocs
v1

API reference / Data Workflows

.md

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.

Last updated 28 Oct 2026API v1

Method
GET
Path
https://api.returning.ai/v1/data-workflows/event-ingests/status
Permission
dataWorkflows
Retries
Read-only; poll with backoff until the status is final

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.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
dataWorkflowsShown in the dashboard as “Data Workflows”

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: <batch_id>.
  • 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 accepted_record_count at 0 and skipped_record_count counting the rows you sent again, 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#

trigger_id#stringREQUIRED
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.

Rule24 hex characters

Eg"66f000000000000000000603"

batch_id#stringREQUIRED
The batch ID you sent in metadata.batch_id. Matched exactly, including capitals.

RuleNon-empty string

Eg"deposits-2026-09-27-001"

Headers#

Authorization#stringREQUIRED
Community API key with dataWorkflows.

RuleBearer <API_KEY>

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 <API_KEY>'

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.

status#stringALWAYS
Result of the lookup.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
Where the batch is now.
trigger_id#stringALWAYS
The trigger_id you asked about.
batch_id#stringALWAYS
The batch_id you asked about.
status#stringALWAYS
Where the batch is. processed, skipped, orphaned and failed are final; see Behaviour.

Rulepending, queued, processing, processed, skipped, orphaned, failed

received_at#stringALWAYS
When the batch was first saved. null when not recorded.
processed_at#stringALWAYS
When the workflow finished with the batch. null until the batch is processed.
accepted_record_count#integerALWAYS
Rows in data that were accepted for the workflow. 0 when not recorded.
skipped_record_count#integerALWAYS
Rows in data that were skipped, such as repeats of a record already received. For a repeated batch_id, every row you sent again. 0 when not recorded.
error#objectALWAYS
The stored failure or skip reason, or null when there is none.
code#string
INGEST_FAILED for a failed or orphaned batch, otherwise INGEST_SKIPPED.

RuleINGEST_FAILED or INGEST_SKIPPED

message#string
The stored reason, such as Duplicate batch_id received: deposits-2026-09-27-001. Do not branch on it.
{
  "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 request04

401Fix the request
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.
400INVALID_TRIGGER_IDFix the request
trigger_id is missing, sent twice, or isn't 24 hex characters. Send the workflow's Production Trigger ID once.
400MISSING_BATCH_IDFix the request
batch_id is missing, blank or sent twice. Send the metadata.batch_id of the batch you're checking.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.

Fix the data02

404EVENT_INGEST_NOT_FOUNDFix the data
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.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.

Retry with backoff02

500EVENT_INGEST_STATUS_LOOKUP_FAILEDRetry with backoff
The status could not be read. Retry the same request with exponential backoff.
500AUTHENTICATION_FAILEDRetry with backoff
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, requests return 429; wait for the window to reset, then retry.

{
  "meta": {
    "status": "error",
    "statusCode": 401,
    "code": "AUTHENTICATION_REQUIRED"
  },
  "message": "API request rejected error.",
  "detail": "A valid bearer token or API key is required for this endpoint.",
  "solution": "Read error detail and try again."
}

Next step#

Get user field histories for a specific userGET/v1/communities/{communityId}/users/{userId}/user-field-historiesOnce the batch is processed, check what the workflow changed for a trader.