API reference / Runs

Runs

A run is one execution attempt of a job. Every attempt, successful or not, is recorded with its HTTP status, duration, and any error message returned by your target. Runs are read-only. Retention depends on your plan: 3 days on Hobby, 30 on Pro, and 90 on Scale, after which runs are deleted while the parent job record remains.

The run object

Field	Type	Description
`id`	string	Unique run identifier, prefixed `run_`. Immutable.
`job_id`	string	ID of the job this run belongs to.
`attempt`	integer	Attempt number, starting at 1.
`status`	string	One of `running`, `succeeded`, `failed`, or `timed_out`. A run that exceeds 15 minutes is marked `timed_out`.
`response_status`	integer	HTTP status code returned by the target, or `null` if no response was received.
`error`	string	Error message or truncated response body for failed attempts, or `null` on success.
`started_at`	string (ISO 8601)	When the attempt began, in UTC.
`duration_ms`	integer	Elapsed time of the attempt in milliseconds. `null` while running.
`next_retry_at`	string (ISO 8601)	When the next attempt is scheduled, or `null` if none remains.

#List runs

GET /v2/runs

Returns runs across the project in reverse chronological order, paginated with limit (default 50, maximum 200) and cursor. Filter by job_id or status to narrow results. Only runs within your plan's retention window are returned.

Parameter	In	Type	Required	Description
`job_id`	query	string	no	Return only runs belonging to this job.
`status`	query	string	no	Filter by `running`, `succeeded`, `failed`, or `timed_out`.
`limit`	query	integer	no	Page size. Default 50, maximum 200.
`cursor`	query	string	no	The `next_cursor` value from the previous response.

Shell

curl "https://api.tendcomputer.com/v2/runs?job_id=job_01HZX7Q4M2" \
  -H "Authorization: Bearer tnd_live_8fQ2xLm9Zc41"

JSON

{
  "data": [
    {
      "id": "run_01HZXC8V2P",
      "job_id": "job_01HZX7Q4M2",
      "attempt": 2,
      "status": "succeeded",
      "response_status": 200,
      "error": null,
      "started_at": "2026-05-14T09:00:07Z",
      "duration_ms": 412,
      "next_retry_at": null
    },
    {
      "id": "run_01HZXC7B1N",
      "job_id": "job_01HZX7Q4M2",
      "attempt": 1,
      "status": "failed",
      "response_status": 503,
      "error": "Service Unavailable",
      "started_at": "2026-05-14T09:00:00Z",
      "duration_ms": 1186,
      "next_retry_at": "2026-05-14T09:00:07Z"
    }
  ],
  "next_cursor": null
}

#Retrieve a run

GET /v2/runs/{run_id}

Returns a single run with its response status, duration, and error detail. Use it to find out why a particular attempt failed without paging through a job's full history. Runs older than your plan's retention window return resource_not_found.

Parameter	In	Type	Required	Description
`run_id`	path	string	yes	The run ID, beginning with `run_`.

Shell

curl https://api.tendcomputer.com/v2/runs/run_01HZXC7B1N \
  -H "Authorization: Bearer tnd_live_8fQ2xLm9Zc41"

JSON

{
  "id": "run_01HZXC7B1N",
  "job_id": "job_01HZX7Q4M2",
  "attempt": 1,
  "status": "failed",
  "response_status": 503,
  "error": "Service Unavailable",
  "started_at": "2026-05-14T09:00:00Z",
  "duration_ms": 1186,
  "next_retry_at": "2026-05-14T09:00:07Z"
}

#Retry a failed run

POST /v2/runs/{run_id}/retry

Manually queues a new attempt for the job that owns a failed run, outside the automatic backoff schedule. The new attempt counts toward the job's max_attempts unless the job has already exhausted them, in which case the job is reopened for exactly one additional attempt. Runs that are running or succeeded cannot be retried.

Parameter	In	Type	Required	Description
`run_id`	path	string	yes	The ID of a run with status `failed` or `timed_out`.
`Idempotency-Key`	header	string	no	Prevents a double click from queuing two attempts. Valid for 24 hours.

Shell

curl -X POST https://api.tendcomputer.com/v2/runs/run_01HZXD2K9S/retry \
  -H "Authorization: Bearer tnd_live_8fQ2xLm9Zc41" \
  -H "Idempotency-Key: manual-retry-run-01HZXD2K9S"

JSON

{
  "id": "run_01HZXD5M4T",
  "job_id": "job_01HZX9B7T5",
  "attempt": 6,
  "status": "running",
  "response_status": null,
  "error": null,
  "started_at": "2026-05-13T17:41:09Z",
  "duration_ms": null,
  "next_retry_at": null
}