---
title: "Start a new agent run"
method: POST
path: "/v1/runs"
tags: ["Runs"]
---

# Start a new agent run

`POST /v1/runs`

Start tracking a new agent run for a customer workflow.

Returns a run ID that can be used to emit events and track execution.
The run starts in PENDING status and transitions to RUNNING when the first event is emitted.

## Request body

- object
  - `customerId` string, required — Customer ID (must exist)
  - `workflowId` string, required — Workflow ID (must exist)
  - `externalRunId` string — Your system run ID (must be unique per business)
  - `correlationId` string — Cross-service tracing ID for linking runs across services
  - `parentRunId` string — Parent run ID for nested/sub-runs
  - `metadata` object — Arbitrary metadata to attach to the run

## Response `201`

Run started

- object — Run started
  - `id` string
  - `customerId` string
  - `workflowId` string
  - `workflowName` string
  - `status` string
  - `correlationId` string, nullable
  - `createdAt` string, date-time

## Other responses

- `400` — Validation error
- `401` — Unauthorized
- `404` — Customer or workflow not found
- `409` — Run with externalRunId already exists
- `429` — Rate limit exceeded
- `503` — Service temporarily unavailable

---

[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)