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

# Get Run

> Poll the current status, spend, and findings of a Nyx run

## Overview

Returns the full state of a Nyx run. Poll this endpoint after [submitting a run](/api-reference/nyx/endpoint/submit-run) until `status` reaches a terminal state (`completed`, `failed`, or `cancelled`). The CLI polls every 5 seconds; client code should respect a similar cadence.

## Path Parameters

<ParamField path="run_id" type="string" required>
  The `run_id` returned by `POST /nyx/runs`.
</ParamField>

## Response

<ResponseField name="run_id" type="string" required />

<ResponseField name="config_name" type="string" required />

<ResponseField name="name" type="string" required>
  Human-readable audit name.
</ResponseField>

<ResponseField name="status" type="enum" required>
  One of: `"queued"`, `"running"`, `"completed"`, `"failed"`, `"cancelled"`.
</ResponseField>

<ResponseField name="result" type="enum | null" required>
  Terminal outcome. `null` while running, otherwise:

  * `"success"`: vulnerability found
  * `"exhausted"`: budget exhausted, no finding
  * `"error"`: internal failure
</ResponseField>

<ResponseField name="budget_usd" type="number" required>
  Configured budget cap.
</ResponseField>

<ResponseField name="spent_usd" type="number" required>
  Cumulative spend so far.
</ResponseField>

<ResponseField name="attempts_completed" type="integer" required>
  Number of probe attempts Nyx has finished.
</ResponseField>

<ResponseField name="findings_count" type="integer" required>
  Number of vulnerabilities saved during the run.
</ResponseField>

<ResponseField name="created_at" type="datetime" required />

<ResponseField name="updated_at" type="datetime" required />

<ResponseField name="completed_at" type="datetime | null" required>
  Set once the run reaches a terminal state.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.fabraix.com/v1/nyx/runs/r_01H2X3Y4Z5 \
    -H "X-Verification-Token: $NYX_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  async function pollUntilDone(runId) {
    const terminal = ['completed', 'failed', 'cancelled'];
    while (true) {
      const res = await fetch(`https://api.fabraix.com/v1/nyx/runs/${runId}`, {
        headers: { 'X-Verification-Token': process.env.NYX_TOKEN },
      });
      const run = await res.json();
      console.log(`${run.status}: $${run.spent_usd}/$${run.budget_usd}`);
      if (terminal.includes(run.status)) return run;
      await new Promise(r => setTimeout(r, 5000));
    }
  }
  ```
</CodeGroup>

### Running

```json theme={null}
{
  "run_id": "r_01H2X3Y4Z5",
  "config_name": "playground",
  "name": "Fabraix Playground: The Gatekeeper",
  "status": "running",
  "result": null,
  "budget_usd": 5.00,
  "spent_usd": 1.23,
  "attempts_completed": 7,
  "findings_count": 0,
  "created_at": "2026-04-18T14:30:45.123Z",
  "updated_at": "2026-04-18T14:35:12.456Z",
  "completed_at": null
}
```

### Completed: Vulnerability Found

```json theme={null}
{
  "run_id": "r_01H2X3Y4Z5",
  "config_name": "playground",
  "name": "Fabraix Playground: The Gatekeeper",
  "status": "completed",
  "result": "success",
  "budget_usd": 5.00,
  "spent_usd": 2.87,
  "attempts_completed": 14,
  "findings_count": 1,
  "created_at": "2026-04-18T14:30:45.123Z",
  "updated_at": "2026-04-18T14:42:01.789Z",
  "completed_at": "2026-04-18T14:42:01.789Z"
}
```

When `result` is `"success"`, fetch the [report](/api-reference/nyx/endpoint/get-report) to see the finding details.

## Related Endpoints

* [POST /nyx/runs](/api-reference/nyx/endpoint/submit-run): submit a new run
* [GET /nyx/runs/{run_id}/report](/api-reference/nyx/endpoint/get-report): download the markdown report