---
title: "Record a complete run in one call"
method: POST
path: "/v1/runs/record"
tags: ["Runs"]
---

# Record a complete run in one call

`POST /v1/runs/record`

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.

## Request body

- object
  - `customerId` string, required — Drip customer ID (cus_*)
  - `workflow` string, required — Workflow slug/name or workflow ID (wf_*)
  - `events` object[] — Ordered list of events to attach to the run
    - `eventType` string, required — Event name for this step (for example llm.call, tool.call, agent.plan)
    - `quantity` number — Optional numeric quantity for the event
    - `units` string — Optional unit label for quantity
    - `description` string — Optional human-readable label or summary
    - `costUnits` number — Optional cost attributed to this event
    - `metadata` object — Optional structured metadata such as model, token breakdown, latency, or tool details
  - `status` 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'TIMEOUT', required — Final run status
  - `errorMessage` string — Optional failure message when status is FAILED
  - `errorCode` string — Optional machine-readable failure code
  - `externalRunId` string — Optional idempotent run identifier from your system
  - `correlationId` string — Optional trace or request ID for cross-system correlation
  - `metadata` object — Optional metadata stored on the run itself

## Response `201`

Run recorded

- object — Run recorded
  - `run` object
    - `id` string
    - `workflowId` string
    - `workflowName` string
    - `status` string
    - `durationMs` integer, nullable
  - `events` object
    - `created` integer
    - `duplicates` integer
  - `totalCostUnits` string, nullable
  - `summary` string

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Customer or workflow not found
- `409` — Run with externalRunId already exists

---

[API](https://skmtc.net/usedrip/apis/drip-api.md) · [All operations](https://skmtc.net/usedrip/apis/drip-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usedrip/drip-api/revisions/2cb1567969ca/schema)