---
search:
  tags:
    - Runs
    - POST
seo:
  description: >-
    Sending an idempotencyKey that was used before returns the existing run, in
    any status, with… Reference for the POST /v1/runs endpoint in the looot API.
sidebar:
  label: Create a run
  badge: POST
title: Create a run
type: openapi-operation
---
Sending an `idempotencyKey` that was used before returns the existing run, in any status, with `replayed: true`. No new run is created.

Dispatch starts at once for the run's workspace, and the call returns at once unless `wait` says otherwise. `wait` works as this query parameter or as a body field of the same name; the query parameter wins when both are set. `wait=true` (or a bare `?wait`) waits up to the default of 20 s; a number is seconds, clamped to 0-60.

If the run reaches a terminal status within `wait` seconds, the answer carries the result inline, in the same run shape. If it is still queued or running when the window ends, you get that queued or running run, as with no `wait` at all; poll it with GET /v1/runs/{runId} or `runs_get`.

A 201 can carry `status: "failed"` for a denial before dispatch, such as `endpoint_not_found` or a `validation_error`. Check the run's own `status` and `error` fields, not the HTTP status code alone, to know whether it ran.

`POST /v1/runs`