API Reference
Conventions shared by every endpoint, and where each endpoint is documented.
Base URL
Your API base URL is set up with your workspace. The examples read it from NEXQDATA_API:
export NEXQDATA_API="<your API base URL>"All paths below are relative to it, and start with /api.
Authentication
Every request sends an API key — X-Api-Key: nxd_live_… or Authorization: Bearer nxd_live_…. See Authentication.
Requests and responses
- Bodies are JSON (
Content-Type: application/json). - Ids are GUIDs, except an agent's
externalAgentId, which is a string. See Agent ids. - Times are ISO 8601, in UTC unless a field says otherwise.
- Every JSON response uses one envelope:
{
"success": true,
"message": "Job started.",
"data": { },
"errorCode": null
}File downloads return the file itself, not an envelope.
Endpoints
Every endpoint in these docs, grouped by area. Each area links to the page that documents it.
Agents
| Method | Path | Does |
|---|---|---|
GET | /api/scraper-agents | List your agents |
GET | /api/scraper-agents/{id} | Read one agent |
GET | /api/scraper-agents/{id}/sample-output | Read the agent's sample output |
GET | /api/scraper-agents/{id}/sample-output/download | Download the sample as JSON |
Running
| Method | Path | Does |
|---|---|---|
POST | /api/scraper-agents/{externalAgentId}/start-job | Start a job (recommended) |
POST | /api/scraper-agents/{externalAgentId}/run | Start a single run |
POST | /api/scraper-agents/runs/{runId}/stop | Stop a run |
Jobs
| Method | Path | Does |
|---|---|---|
GET | /api/scraper-agents/jobs | Jobs across your agents |
GET | /api/scraper-agents/{id}/jobs | One agent's jobs |
GET | /api/scraper-agents/jobs/{jobId}/runs | A job's runs |
GET | /api/scraper-agents/jobs/{jobId}/export | Download a job's data |
GET | /api/scraper-agents/jobs/{jobId}/dataset | A job's dataset id |
GET | /api/scraper-agents/jobs/active-count | Jobs in progress |
GET | /api/scraper-agents/jobs/status-counts | Jobs by status |
Runs
| Method | Path | Does |
|---|---|---|
GET | /api/scraper-agents/{id}/runs | One agent's runs |
GET | /api/scraper-agents/runs | Runs across your agents |
POST | /api/scraper-agents/runs/{runId}/refresh | Re-read a run's state |
POST | /api/scraper-agents/runs/{runId}/dismiss-attention | Ignore a failure |
POST | /api/scraper-agents/runs/{runId}/restore-attention | Track a failure again |
GET | /api/scraper-agents/runs/active-count | Runs in progress |
GET | /api/scraper-agents/runs/attention-count | Failures needing attention |
GET | /api/scraper-agents/runs/status-counts | Runs by status |
Groups
| Method | Path | Does |
|---|---|---|
GET | /api/search-groups | List groups |
GET | /api/search-groups/{id} | Read one group |
POST | /api/search-groups | Create a group |
PUT | /api/search-groups/{id} | Rename, describe, or disable a group |
PUT | /api/search-groups/{id}/members | Replace a group's members |
DELETE | /api/search-groups/{id} | Delete a group |
POST | /api/search-groups/{groupId}/run | Run a group |
GET | /api/search-groups/runs | List group runs |
GET | /api/search-groups/runs/{groupRunId} | Follow a group run |
POST | /api/search-groups/runs/{groupRunId}/members/{agentId}/retry | Start a member that didn't start |
DELETE | /api/search-groups/runs/{groupRunId} | Delete a group run |
GET | /api/scraper-agents/group-runs/{groupRunId}/export | Download a group run's data |
Pipelines
| Method | Path | Does |
|---|---|---|
GET | /api/pipelines | List pipelines |
GET | /api/pipelines/{id} | Read one pipeline |
POST | /api/pipelines | Create a pipeline |
PUT | /api/pipelines/{id} | Rename, describe, or disable a pipeline |
PUT | /api/pipelines/{id}/steps | Replace a pipeline's stages |
DELETE | /api/pipelines/{id} | Delete a pipeline |
POST | /api/pipelines/{pipelineId}/run | Run a pipeline |
GET | /api/pipelines/runs | List pipeline runs |
GET | /api/pipelines/runs/{pipelineRunId} | Follow a pipeline run |
GET | /api/pipelines/runs/{pipelineRunId}/export | Download a pipeline run's data |
DELETE | /api/pipelines/runs/{pipelineRunId} | Delete a pipeline run |
Schedules
| Method | Path | Does |
|---|---|---|
GET | /api/schedules | List schedules |
GET | /api/schedules/page | List schedules, paged |
POST | /api/schedules | Create a schedule |
POST | /api/schedules/preview | Preview run times |
PUT | /api/schedules/{id} | Replace a schedule |
DELETE | /api/schedules/{id} | Delete a schedule |
POST | /api/schedules/{id}/enabled | Enable or pause |
POST | /api/schedules/{id}/run | Run now |
POST | /api/schedules/bulk/enabled | Enable or pause several |
POST | /api/schedules/bulk/delete | Delete several |
GET | /api/schedules/upcoming | Upcoming runs |
Datasets
| Method | Path | Does |
|---|---|---|
GET | /api/scraper-agents/runs/{runId}/export | Download a run's data |
GET | /api/scraper-agents/runs/{runId}/dataset | A run's dataset id |
GET | /api/data-explorer/datasets/{datasetId}/preview | Preview |
POST | /api/data-explorer/datasets/{datasetId}/query | Search, filter, sort, and page |
GET | /api/data-explorer/datasets/{datasetId}/download | Download |
Managing datasets
| Method | Path | Does |
|---|---|---|
GET | /api/scraper-agents/cached-exports | List your datasets |
DELETE | /api/scraper-agents/cached-exports/{datasetId} | Delete a dataset |
GET | /api/data-explorer/datasets/{datasetId}/lineage | Where it came from |
GET | /api/data-explorer/datasets/{datasetId}/access | Read sharing |
PUT | /api/data-explorer/datasets/{datasetId}/access | Share with your company |
POST | /api/data-explorer/bulk/export | Export several as one zip |
POST | /api/data-explorer/bulk/delete | Delete several |
GET | /api/data-explorer/saved-queries | List saved queries |
POST | /api/data-explorer/saved-queries | Save a query |
DELETE | /api/data-explorer/saved-queries/{id} | Delete a saved query |
API keys
| Method | Path | Does |
|---|---|---|
GET | /api/api-keys | List your keys |
POST | /api/api-keys | Generate a key (revokes the active one) |
DELETE | /api/api-keys/{id} | Revoke a key |
Generated reference coming next
Full request and response schemas for every endpoint will be generated from the API's OpenAPI contract, so they stay in step with the API itself.