Run status & history

Most integrations follow a job rather than its runs. When you need run-level detail — each session's status, pages, errors, and timing — list the runs directly. There's no call that waits for a run; you check on it.

List an agent's runs

GET/api/scraper-agents/{id}/runs

Uses the agent's id (GUID). Newest runs come first.

Query parameter	Default	Description
`state`	`all`	`all`, `active`, `succeeded`, or `failed`. Anything else returns `400 INVALID_STATE`.
`pageSize`	`25`	Up to `100`.
`cursor`	—	The `nextCursor` from the previous page. See Pagination.

curl "$NEXQDATA_API/api/scraper-agents/$AGENT_ID/runs?state=active" \
  -H "X-Api-Key: $NEXQDATA_API_KEY"

200 OK — abridged

{
  "success": true,
  "data": {
    "items": [
      {
        "agentRunHistoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "agentName": "Court records · TX",
        "status": "Running",
        "isRunning": true,
        "isTerminal": false,
        "startTime": "2026-09-23T02:00:04Z",
        "endTime": null,
        "runTimeSeconds": null,
        "pages": 12,
        "requests": 31,
        "errors": 0,
        "data": 0,
        "runtimeAnomaly": "None",
        "triggerSource": "Manual"
      }
    ],
    "nextCursor": null
  }
}

Knowing when a run is done

A run is finished when isTerminal is true. To know whether it succeeded, filter rather than reading status:

state=active — still going.
state=succeeded — finished and its data is ready.
state=failed — finished without data; statusMessage says why.

Don't match on the status text

status is reported by the execution engine, and a successful run can read Succeeded or Completed. The state filter accounts for that; string matching doesn't.

Polling

Check every 5–15 seconds while a run is active. Checking status isn't rate-limited, but there's no benefit to polling faster than the run can progress.

Useful fields

Field	Meaning
`agentRunHistoryId`	The run id. A job lists its runs at `GET /api/scraper-agents/jobs/{jobId}/runs`; `run` returns them in `agentRunHistoryIds`.
`startTime`, `endTime`, `runTimeSeconds`	When it ran, and for how long.
`pages`, `requests`, `errors`, `data`	What the run did: pages visited, requests made, errors hit, and data items collected.
`statusMessage`	Why a run failed, when it did.
`runtimeAnomaly`	`None`, `Slow`, or `Fast` compared with the agent's usual runtime. A `Fast` run can mean a quiet failure.
`triggerSource`	`Manual` (started from the API or the dashboard) or `Schedule`.

All runs across agents

GET/api/scraper-agents/runs

The same fields and filters, across every agent you can access. Also accepts search (agent name and run details), and from and to dates.

Refresh a run

POST/api/scraper-agents/runs/{runId}/refresh

Re-reads the run's current state from the execution engine and updates its record. It's read-only — nothing is started or stopped. Use it when a run's status looks stale. If the engine no longer has the run, a run that was still open is settled as failed.

Failures that need attention

A failed run is tracked until someone deals with it — tracked failures are what the dashboard's Needs attention view shows. Mark one as handled so it stops counting:

POST/api/scraper-agents/runs/{runId}/dismiss-attention

POST/api/scraper-agents/runs/{runId}/restore-attention

dismiss-attention ignores the failure; restore-attention tracks it again. The run itself doesn't change.

To list them, add attention to a failed-runs query on either run list:

`attention`	Returns
`tracked`	Failures still needing attention.
`ignored`	Failures that were dismissed.

attention only works with state=failed; anything else returns 400 INVALID_ATTENTION_FILTER.

curl "$NEXQDATA_API/api/scraper-agents/runs?state=failed&attention=tracked" \
  -H "X-Api-Key: $NEXQDATA_API_KEY"

Counts

Cheap totals across every agent you can access — for a status badge or a health check, without paging through history.

Endpoint	`data`
`GET /api/scraper-agents/runs/active-count`	Runs still in progress, as a number.
`GET /api/scraper-agents/runs/attention-count`	Failures still needing attention, as a number.
`GET /api/scraper-agents/runs/status-counts`	Runs by status: `all`, `demo`, `starting`, `running`, `delivery`, `succeeded`, `failed`, `stopped`.

Jobs

Every run started through a job — including group, pipeline, and schedule runs — is grouped under it. See Jobs.

On this page