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 to fetch status and results.

clay routines runs start <routineId> (--input <json|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 <json|file|->	Run body as a JSON object matching { "items": [{ "id": <string>, "inputs": <object> }] }. Pass inline JSON, a file path, or - for stdin. items accepts 1 to 100 entries; use --bulk for larger batches.
--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"
}

Field	Type	Description
routineRunId	string	Pass to clay 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, or the routine is not enabled for API & CLI.
auth_forbidden	3	The API key lacks access to run this routine through API & CLI.
server_error	1	Bulk input upload to storage failed. Safe to retry the command.

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