Running an agent
Start an agent with your inputs as a job, and stop a run in progress.
Start a job
/This is the recommended way to start an agent. It's what the NexqData platform itself uses — the dashboard's run and start-job actions, groups, pipelines, and schedules all start agents this way. A job creates one or more runs, depending on how the agent is built — for example, splitting a large search across sessions — and gives you one id for all of them.
Uses the agent's externalAgentId. The body is optional.
| Field | Type | Description |
|---|---|---|
inputParameters | string | The agent's inputs as a JSON-encoded string, e.g. "{\"LastName\":\"Doe\"}". Keys come from the agent's input parameters. |
curl -X POST "$NEXQDATA_API/api/scraper-agents/$EXTERNAL_AGENT_ID/start-job" \
-H "X-Api-Key: $NEXQDATA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputParameters": "{\"LastName\":\"Doe\"}"}'A 200 OK means the job started — not that it finished. It completes in the background:
{
"success": true,
"message": "Job started.",
"data": {
"agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"externalAgentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"agentJobHistoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jobRunId": 48213,
"sessionId": "",
"startedAt": "2026-09-23T02:00:04Z"
}
}Keep agentJobHistoryId — it's the job id. Use it to follow the job and download its data.
If the agent can't be started, you get 400 with a readable message saying why.
Start a single run
/Starts one run directly, without a job. It takes the same body, and returns the ids of the runs it created in agentRunHistoryIds, which you follow through run history:
{
"success": true,
"message": "Agent run started.",
"data": {
"started": true,
"lastRunStatus": "Running",
"agentRunHistoryIds": ["3fa85f64-5717-4562-b3fc-2c963f66afa6"]
}
}If the agent can't be started, you get 400 with errorCode: "RUN_START_FAILED".
Prefer start-job
run still works, but the platform doesn't use it. Use start-job so your integration behaves like the dashboard, and so agents that split their work across several runs are followed and exported as one.
Stop a run
/Stops a run that's still in progress. Runs that have already finished can't be stopped. To stop a job, stop its runs — list them with GET /api/scraper-agents/jobs/{jobId}/runs.
Rate limits
Starting jobs and runs is rate-limited per user — by default, 60 per minute.