> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# routines runs start

> Start an async routine run.

Start an inline or bulk async routine run. The command returns immediately with a run id — it does not poll or wait. Use [`clay routines runs get`](/cli/reference/routines-runs-get) to fetch status and results.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clay routines runs start <routineId> (--input <file|->) | (--bulk <file.jsonl>)
```

Exactly one of `--input` or `--bulk` is required.

## Arguments

| Argument    | Description                                     |
| ----------- | ----------------------------------------------- |
| `routineId` | Routine id, e.g. `function:t_abc123`. Required. |

## Flags

| Flag                  | Description                                                                                                                                |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `--input <file\|->`   | Inline run body as a JSON object matching `{ "items": [{ "id": <string>, "inputs": <object> }] }`. Use `-` for stdin.                      |
| `--bulk <file.jsonl>` | JSONL file for a batch run. Each line is `{ "id": <string>, "inputs": <object> }`. The file is uploaded to Clay before the run is started. |
| `--webhook-id <id>`   | Registered webhook id to notify when the run finishes. See [`clay webhooks`](/cli/reference/webhooks).                                     |

## Output

Inline run:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "routineRunId": "run_abc123",
  "mode": "inline",
  "status": "in_progress"
}
```

Bulk run:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "routineRunId": "run_abc123",
  "mode": "bulk",
  "status": "in_progress",
  "fileId": "file_xyz789"
}
```

| Field          | Type                 | Description                                                           |
| -------------- | -------------------- | --------------------------------------------------------------------- |
| `routineRunId` | string               | Pass to [`clay routines runs get`](/cli/reference/routines-runs-get). |
| `mode`         | `"inline" \| "bulk"` | Which mode was used.                                                  |
| `status`       | `"in_progress"`      | Always `"in_progress"` at start.                                      |
| `fileId`       | string (bulk only)   | Id of the uploaded JSONL file.                                        |

## Errors

| Code               | Exit | Notes                                                                                                                                                                        |
| ------------------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `validation_error` | 2    | Missing or conflicting input flags, unreadable file, invalid JSON body, or a JSONL row that fails the `{ "id": <string>, "inputs": <object> }` shape (error names the line). |
| `not_found`        | 6    | No routine with that id in this workspace.                                                                                                                                   |
| `auth_forbidden`   | 3    | The API key lacks access to run this routine.                                                                                                                                |

## Examples

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
cat input.json | clay routines runs start function:t_abc123 --input -
clay routines runs start function:t_abc123 --input input.json | jq -r '.routineRunId'
clay routines runs start function:t_abc123 --input input.json --webhook-id wh_abc123
clay routines runs start function:t_abc123 --bulk rows.jsonl
clay routines runs start function:t_abc123 --bulk rows.jsonl --webhook-id wh_abc123
```