Skip to main content
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 to fetch status and results. 
clay routines runs start <routineId> (--input <file|->) | (--bulk <file.jsonl>)
Exactly one of --input or --bulk is required.

​
Arguments

ArgumentDescription
routineIdRoutine id, e.g. function:t_abc123. Required.

​
Flags

FlagDescription
--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.

​
Output

Inline run: 
{
  "routineRunId": "run_abc123",
  "mode": "inline",
  "status": "in_progress"
}
Bulk run: 
{
  "routineRunId": "run_abc123",
  "mode": "bulk",
  "status": "in_progress",
  "fileId": "file_xyz789"
}
FieldTypeDescription
routineRunIdstringPass to clay routines runs get.
mode"inline" | "bulk"Which mode was used.
status"in_progress"Always "in_progress" at start.
fileIdstring (bulk only)Id of the uploaded JSONL file.

​
Errors

CodeExitNotes
validation_error2Missing 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_found6No routine with that id in this workspace.
auth_forbidden3The API key lacks access to run this routine.

​
Examples

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