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

# Get a run

> GET /api/v1/runs/{runId}

<div className="text-sm font-mono">GET /api/v1/runs/{`{runId}`}</div>

Poll a run's status and, once finished, its report link. Call this on the ids
returned by [Run tests](/api-reference/run-tests) until the status is terminal.

## Request

<ParamField path="runId" type="string" required>
  The run id, in the URL path.
</ParamField>

<ParamField header="Authorization" type="string" required>
  `Bearer <your API key>`.
</ParamField>

## Response

<ResponseField name="id" type="string">
  The run id.
</ResponseField>

<ResponseField name="status" type="string">
  One of `queued`, `running`, `passed`, `failed`, `error`, `cancelled`. The last
  four are terminal.
</ResponseField>

<ResponseField name="reason" type="string | null">
  The agent's explanation of the verdict, when finished.
</ResponseField>

<ResponseField name="videoUrl" type="string | null">
  Direct link to the run's video recording, when available.
</ResponseField>

<ResponseField name="reportUrl" type="string">
  A signed, login-free link to the full run report (valid for 30 days). Good for
  CI logs and PR comments.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -H "Authorization: Bearer $CLICKPROOF_API_KEY" \
    https://clickproof.app/api/v1/runs/RUN_ID
  ```
</RequestExample>

<ResponseExample>
  ```json 200 — running theme={null}
  {
    "id": "b1c2d3e4-1111-2222-3333-444455556666",
    "status": "running",
    "reason": null,
    "videoUrl": null,
    "reportUrl": "https://clickproof.app/share/eyJ…"
  }
  ```

  ```json 200 — passed theme={null}
  {
    "id": "b1c2d3e4-1111-2222-3333-444455556666",
    "status": "passed",
    "reason": "Reached the home screen after completing sign-up.",
    "videoUrl": "https://…/run.mp4",
    "reportUrl": "https://clickproof.app/share/eyJ…"
  }
  ```
</ResponseExample>

## Polling pattern

```bash theme={null}
while true; do
  status=$(curl -s -H "Authorization: Bearer $CLICKPROOF_API_KEY" \
    https://clickproof.app/api/v1/runs/$RUN_ID | jq -r .status)
  case "$status" in
    passed|failed|error|cancelled) break ;;
  esac
  sleep 10
done
echo "final: $status"
```

<Tip>
  Prefer the [`clickproof-ai/run-tests`](/ci-cd/github-actions) Action over
  hand-rolled polling — it handles the whole upload → run → poll → report loop and
  sets the job's exit code for you.
</Tip>