Returning.AIDocs
v1

Guides / Workflow Builder

.md

Set up an event-ingest workflow and check batch status

Event ingest is how a system hands Returning.AI a batch of rows and lets a workflow run once for each accepted batch. The API builds and checks the workflow; the batch's own lifecycle is read through the public event ingest status endpoint.

This page combines the two questions that always arrive together: "is my workflow configured for my envelope?" and "did my batch go through?".

The envelope contract

A sender posts a JSON envelope with three things: the trigger id at the root, the batch id at the root path the trigger is configured for, and an array of rows, each carrying the record id fields the trigger names.

Response
{
  "trigger_id": "<PRODUCTION_TRIGGER_ID>",
  "metadata": { "batch_id": "net-deposit-20260710-001" },
  "data": [
    { "occurred_at": "2026-07-10T12:21:24.001Z", "event_type": "net_deposit.snapshot", "client_id": "<broker-client-id>", "deposit_id": "18774", "net_deposit_delta": 10000 }
  ]
}

That example shows only the event shape a batch carries. It is not a Workflow Builder API request; the batch goes to the event ingest endpoint your account was given, not to the base URL on these pages. Packaging and sending trade batches is covered in Trading volume and rewards and SQS data feed.

1. Create the workflow with the ingest trigger

POSTCreate a workflowcURL
curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"name":"Net deposits","trigger":{"type":"event-ingest","name":"Deposits","options":{"batchIdPath":"metadata.batch_id","recordIdPaths":["deposit_id"]}}}'

Readback: the trigger's _id and its stored options. The _id is the value the sender posts as trigger_id.

To change the paths later, replace the trigger:

PUTCreate or replace the triggercURL
curl --request PUT \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/trigger" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c" \
  --data '{"type":"event-ingest","name":"Deposits","options":{"batchIdPath":"metadata.batch_id","recordIdPaths":["deposit_id","transfer_id"]}}'

2. Understand the two deduplication layers

  • The batch id identifies one submission. The same batch id again is skipped before any row is checked, so an exact retry is always safe and always pays nothing.
  • A record id identifies one row. A record id seen before is skipped even inside a different batch, and other new rows in that batch still run.

Multiple record id paths are independent checks, not a combined key: a repeat of any one of them makes the row a duplicate, and the path name is not part of the identity. If one business record needs several fields, build one namespaced value before sending it, for example server-2:account-88:trade-100, and configure that single path.

A row with no value at any configured record id path is counted as missing and skipped.

3. Route the rows to the right step, then validate

Take every field key from the catalog rather than guessing one: GET /catalog returns platformActionFields.get and platformActionFields.post, each entry carrying the key the step stores, the label the platform stores beside it, and whether the field is builtin or custom.

The trigger's rows are in data. Map the array, not the envelope, unless a step needs the envelope itself. A workflow that fans out per row belongs in a row-level step; a workflow that needs one aggregate belongs in a bulk step.

POSTAdd a stepcURL
curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/nodes" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "If-Match: 162af81f5de4ff2b557a4087de9a9a73a0ed4e621f737787e35a93614cb50d1c" \
  --data '{"type":"platform-action","name":"Read depositor","position":{"after":"trigger"},"options":{"action":"get-user-fields","selectUser":{"type":"email","value":["{{65f1a2b3c4d5e6f708192a41.data[0].email}}"]},"fields":[{"label":"Total XP","field":"total_xp"}]}}'

Then validate and dry-run with a sample envelope:

POSTTest a whole workflowcURL
curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/test" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{"mode":"dry-run","triggerPayload":{"trigger_id":"65f1a2b3c4d5e6f708192a41","metadata":{"batch_id":"batch-0001"},"data":[{"email":"trader@example.com","deposit_id":"D-1","net_deposit_delta":"500"}]}}'

Readback: the trace resolves the row from the seeded payload. A literal expression in the trace means the binding is wrong; see Bind step inputs.

4. Deploy, then read a batch's status

POSTDeploy a workflowcURL
curl --request POST \
  --url "https://api.returning.ai/v1/workflow-builder/data-workflows/65f1a2b3c4d5e6f708192a3b/deploy" \
  --header "Authorization: Bearer <API_KEY>" \
  --header "If-Match: 68f78253046393414dec404e5442c140bb5db0393a7d1c389ff57bba71585501"

After the sender posts a batch, three surfaces answer three different questions:

SurfaceQuestionWhere
Event ingest statusDid the platform receive this batch, and did the workflow run it?GET /v1/data-workflows/event-ingests/status?trigger_id=<triggerId>&batch_id=<batchId>
Bulk update callbackDid the resulting user update finish, and how many rows succeeded?A URL the broker controls, configured on the bulk step
Failure webhookDid a run end in error?The workflow's outgoingWebhookUrl

The status read needs a community API key with the dataWorkflows permission. It is a separate permission from workflowBuilder, and it is the one place dataWorkflows still applies.

Meanings that matter:

  • pending or queued: accepted, waiting. Minutes of wait are normal for a scheduled dispatch.
  • processed: the workflow ran. It does not mean every step succeeded, and it does not mean balances changed.
  • skipped: a duplicate batch id, or every row was a duplicate or had no record id.
  • failed: rejected before running, for example a batch id missing from the configured path.
  • orphaned: no deployed workflow matched the trigger.

Read the run's own result with GET /{workflowId}/runs when you need to know whether steps succeeded. processed and a run error can both be true.

Read the newest status before an exact retry: a retry shows as skipped, which hides the original result.

5. Prove the batch end to end

  1. GET /{workflowId}/runs for the run and GET /runs/{runId} for the step results.
  2. For a bulk step, the bulk update job: status, then per-row details.
  3. The member's own field value.
  4. Your own ledger, to confirm you acknowledged the batch once.

A 2xx from the sender's post proves only that the request was accepted. An ingest row proves it was routed. A run proves it executed. Only the member's value proves the reward.

6. Failure handling

What you seeWhat it meansWhat to do
Ingest failed with a batch id path messageThe batch id was not at the configured root pathFix the sender, resend under a new batch id.
Ingest skippedDuplicate batch, or all rows duplicatedNothing to do unless the data is genuinely new.
Ingest processed, run errorThe workflow ran and a step failedRead the run detail, fix the step.
Status read 404 right after a 2xx ingestThe batch id could not be read, so the row cannot be found by that idCheck the envelope, then ask for the batch on the Event Ingests board.
Bulk job Failed, every row successThe job failed as a whole and nothing was appliedCheck the CSV header names the community's identifier field, then send a new batch.
No ingest row at allThe request never reached the platformConfirm the exact URL the sender posted to resolves, and ask for the sender's exact request.

7. Cleanup

Undeploy when the pipeline should stop, then delete. A deleted workflow takes its run history with it, and ingest rows remain readable only through the sender's batch ids for a short window, so keep your own record of what a canary batch proved.

What the API does not cover

  • Sending a batch. The sender posts the envelope; there is no Workflow Builder route that submits one.
  • The bulk job's own status and per-row details, which are separate platform endpoints.
  • Reading ingest payloads in bulk. The Event Ingests board and its routes are a different surface, and the public status endpoint reads one batch summary.
  • Triggering a dispatch by hand.

Endpoints on this page