Agent groups

An agent group holds agents that cover the same kind of record — every county court, every state licensing board. Running the group starts every member with the same inputs. Each member runs independently, so one slow or failing source never holds up the rest.

List groups

GET/api/search-groups

Returns the groups you can run — those whose every member agent is assigned to you.

GET/api/search-groups/{id}

One group, with its members. Each member has its scraperAgentId and externalAgentId.

Field	Meaning
`isActive`	`false` when the group is disabled and can't be run.
`memberCount`, `members`	The agents in the group.
`activeRunCount`	Member runs from this group still in progress.
`lastRunStatus`, `lastRunAt`	The latest run's outcome — `Pending`, `Stalled`, `Running`, `Succeeded`, or `Failed` — and when it started. `null` if it has never run.
`canManage`	Whether you can edit or delete it — `true` for groups you created.

Run a group

POST/api/search-groups/{groupId}/run

Field	Type	Description
`inputParameters`	string	Inputs applied to every member, as a JSON-encoded string.

curl -X POST "$NEXQDATA_API/api/search-groups/$GROUP_ID/run" \
  -H "X-Api-Key: $NEXQDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputParameters": "{\"LastName\":\"Doe\",\"FirstName\":\"Jane\"}"}'

200 OK

{
  "success": true,
  "message": "Starting 3 agents — track progress on the run.",
  "data": {
    "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "groupRunId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "memberCount": 3
  }
}

Members start in the background, staggered, so the response can't tell you how many started. Use groupRunId to follow them.

Follow a group run

GET/api/search-groups/runs/{groupRunId}

Returns memberCount, startedCount, failedCount, and jobs — one job per member agent, with its own status. Members that never started are listed in notStarted, with the reason.

Retry one member

POST/api/search-groups/runs/{groupRunId}/members/{agentId}/retry

Starts a member that never started, filed under the same group run — without re-running the whole group.

List group runs

GET/api/search-groups/runs

Your past group runs, newest first. This list is paged by page number.

Query parameter	Default	Description
`groupId`	—	Only this group's runs.
`status`	all	`ontrack` — still running. `completed` — finished, every member succeeded. `atrisk` — finished, some members failed. `behind` — finished, nothing succeeded.
`q`	—	Matches the group name or the run id.
`from`, `to`	—	Only runs started in this date range.
`page`, `pageSize`	`1`, `25`	`pageSize` up to `100`.

The response has items, total, and metrics — total, completed, inProgress, and issues across all your group runs.

Download the results

GET/api/scraper-agents/group-runs/{groupRunId}/export

One zip with one file per member agent. Results aren't merged across sources — each file keeps its source's own fields.

Create and manage groups

You can build groups from the agents assigned to you, and edit or delete the groups you created. Groups set up for you by NexqData can be run but not changed — for those, canManage is false and edits return 404.

POST/api/search-groups

Request body

{
  "name": "Court records — Southwest",
  "description": "Every county court we cover in TX, NM, and AZ.",
  "agentIds": [
    "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "3fa85f64-5717-4562-b3fc-2c963f66afa7"
  ]
}

agentIds are agent ids (GUIDs), not externalAgentIds. Including an agent that isn't assigned to you returns 400.

Endpoint	Does
`PUT /api/search-groups/{id}`	Change `name` or `description`, or disable the group with `isActive: false`. Fields you leave out stay as they are.
`PUT /api/search-groups/{id}/members`	Replace the members with `{ "agentIds": [...] }`.
`DELETE /api/search-groups/{id}`	Delete the group. Its past runs are kept.
`DELETE /api/search-groups/runs/{groupRunId}`	Delete one of your group runs, with its member jobs and run history.

Deleting a run is permanent

Deleting a group run removes its jobs and run history, and it can't be undone.

Live Search is built on groups

Searching many sources on demand is a group run with the inputs you have. See Live Search.