Returning.AIDevelopers
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 26 Sep 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 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#

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. 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.
{
  "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.