Sign in

v1

latestOpenAPI 3.1.02026-08-042453938.9 KB
Runs

Record a complete run in one call

One-call convenience endpoint that atomically creates a workflow (if needed), starts a run, emits events, and ends the run.

This replaces the 4-step SDK orchestration:

  1. GET /workflows (resolve slug)
  2. POST /runs (start)
  3. POST /run-events/batch (emit events)
  4. PATCH /runs/:id (end)

The workflow field can be a workflow ID or a slug. If a slug is provided and no matching workflow exists, one is auto-created.

post/v1/runs/record

Request body

customerIdstring required

Drip customer ID (cus_*)

workflowstring required

Workflow slug/name or workflow ID (wf_*)

status'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT' required

Final run status

errorMessagestring

Optional failure message when status is FAILED

errorCodestring

Optional machine-readable failure code

externalRunIdstring

Optional idempotent run identifier from your system

correlationIdstring

Optional trace or request ID for cross-system correlation

metadataobject

Optional metadata stored on the run itself

Example request

{
  "customerId": "cus_abc123",
  "workflow": "research-agent",
  "events": [
    {
      "eventType": "llm.call",
      "quantity": 1700,
      "units": "tokens",
      "description": "web-search",
      "costUnits": 0.35,
      "metadata": {
        "model": "gpt-4",
        "inputTokens": 500,
        "outputTokens": 1200
      }
    }
  ],
  "status": "COMPLETED",
  "errorMessage": "Provider returned rate_limited",
  "errorCode": "rate_limited",
  "externalRunId": "job_123",
  "correlationId": "trace_abc123",
  "metadata": {
    "tenant": "acme",
    "environment": "production"
  }
}

Response

Run recorded

totalCostUnitsstring nullable
summarystring