dataWorkflows) permission in Authorization: Bearer <API_KEY>. If you need to find the workflow ID with List workflows, that operation uses the separate workflowBuilder permission.workflow_id and event_keys as JSON. The lookup is scoped to the API key's community and the supplied workflow ID. It reads receipts without awarding or reversing anything.event_key and found: false. A well-formed workflow ID with no matching receipts also returns 200 with found: false for every key. A found receipt includes all the fields shown in the example. Unavailable values are null, and metadata defaults to {}.actual_rewards on a completed original to reconcile what was awarded. A completed reversal records that the saved award was deducted. The original actual_rewards still shows the award and the lookup shows the cancellation under reversal. Look up the original key to see both. A cancellation key has no receipt of its own.processed while its reward updates are still queued. For found: false or status: processing with has_error: false, retry the lookup later. Apply the same rule to a reversal still processing without an error. Record a deduction only after its reversal is completed. Flag a receipt for manual reconciliation when it reports an error or stays unresolved past your reconciliation window.meta.code for structured errors and meta.errors for invalid fields. Malformed JSON can return 400 before body validation. If your community opts into API rate limiting, a request over the limit returns 429 with meta.code: RATE_LIMITED and a Retry-After header in seconds.| HTTP | Code | What to do |
|---|---|---|
| 400 | VALIDATION_ERROR | Check meta.errors and fix the request body before retrying. |
| 401 | AUTHENTICATION_REQUIRED | Send a valid community API key in the Authorization header. |
| 403 | API_KEY_PERMISSION_DENIED | Grant the community key Data Workflows permission. |
| 403 | COMMUNITY_ACCESS_DENIED | Use a community API key for the workflow's community. |
| 404 | COMMUNITY_NOT_FOUND | Check that the API key belongs to an existing community. |
| 429 | RATE_LIMITED | Wait for the time in the Retry-After header before calling again. |
| 500 | AUTHENTICATION_FAILED | Retry the read with backoff. |
| 500 | INTERNAL_ERROR | Retry the read with backoff. |
curl --location 'https://api.returning.ai/v1/data-workflows/reward-events/lookup' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"workflow_id": "66f000000000000000000001",
"event_keys": [
"trade-1001",
"trade-1002"
]
}'{
"status": "success",
"message": "Reward events fetched successfully",
"data": {
"workflow_id": "66f000000000000000000001",
"results": [
{
"event_key": "trade-1001",
"found": true,
"status": "completed",
"account_id": "account-88",
"trade_id": "1001",
"occurred_at": "2026-11-20T08:00:00.000Z",
"requested_rewards": {
"xp": 100,
"coins": 100
},
"actual_rewards": {
"xp": 100,
"coins": 80,
"premium_coins": 0,
"premium_currency_id": null
},
"metadata": {
"instrument": "EURUSD"
},
"has_error": false,
"completed_at": "2026-11-20T08:05:00.000Z",
"reversal": {
"event_key": "cancel-trade-1001",
"status": "completed",
"occurred_at": "2026-11-20T09:00:00.000Z",
"claimed_at": "2026-11-20T09:04:00.000Z",
"completed_at": "2026-11-20T09:05:00.000Z",
"has_error": false
}
},
{
"event_key": "trade-1002",
"found": false
}
]
}
}