For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
The Parallel Task Group API enables you to batch process hundreds or thousands of Tasks efficiently. Instead of running Tasks one by one, you can organize them into groups, monitor their progress collectively, and retrieve results in bulk. The API is comprised of the following endpoints:
Creation: To run a batch of tasks in a group, you first need to create a task group, after which you can add runs to it, which will be queued and processed.
.md to its URL or sending Accept: text/markdown.POST /v1/tasks/groups(Create task-group)POST /v1/tasks/groups/{taskgroup_id}/runs(Add runs. Up to 1,000 runs per POST request.)
GET /{taskgroup_id} and GET /{taskgroup_id}/runs. The runs endpoint streams back the requested runs immediately using SSE to support large payloads without pagination; it does not wait for runs to complete. Task Group runs are subject to your account’s data-retention configuration. Persist any results your application needs after processing; Zero Data Retention (ZDR) deployments do not retain completed run data.
GET /v1/tasks/groups/{taskgroup_id}(Get task-group summary)GET /v1/tasks/groups/{taskgroup_id}/runs(Fetch task group runs)GET /v1/tasks/groups/{taskgroup_id}/runs/{run_id}(Retrieve one task run’s status)
GET /{taskgroup_id}/events. To retrieve a completed task run’s result, use the task run result endpoint.
GET /v1/tasks/groups/{taskgroup_id}/events(Stream task-group events)GET /v1/tasks/runs/{run_id}/result(Get task-run result)
Key Concepts
Task Groups
A Task Group is a container that organizes multiple task runs. Each group has:- A unique
taskgroup_idfor identification - A status object with
is_active(boolean) andtask_run_status_counts(counts by status) - The ability to add new Tasks dynamically
Group Status
Track progress with real-time status updates:- Total number of task runs
- Count of runs by status (
queued,action_required,running,completed,failed,cancelling, orcancelled) - Whether the group is active (
is_activeistruewhile any run isqueued,running, orcancelling)
task_run_status_counts to distinguish those outcomes.
Quick Start
1. Define Types and Task Structure
2. Create a Task Group
3. Add Tasks to the Group
By default, the response refreshes and returns the aggregated status of all runs in the group. If you’re adding tasks at scale, setrefresh_status to false to skip the full status refresh — the response still includes a status snapshot from the group’s atomically maintained counters. You can refresh the aggregated status at any time via the GET task-group endpoint.
4. Monitor Progress
5. Retrieve Results
ThegetRuns endpoint returns a Server-Sent Events stream, not a simple JSON response. It emits one event per run currently in the group (a snapshot of each run’s state), then closes. To pick up runs added after that snapshot, resume from the last event_id via the last_event_id parameter.
Each event in the stream has:
type: Either"task_run.state"or"error"event_id: Cursor for resuming the stream via thelast_event_idparameterrun: TheTaskRunobject withrun_id,status, andis_activeinput: The original input (only included wheninclude_input=true)output: The result output (only included wheninclude_output=trueand the run completed successfully)
/events endpoint shown below the getRuns examples.
Batch Processing Pattern
For large datasets, process Tasks in batches to optimize performance. Settingrefresh_status to false is recommended when adding tasks in bulk, as it skips refreshing the group status on each request for faster responses:
Error Handling
The/runs stream is a snapshot and can include active runs. Classify each event using event.run.status, not merely by whether an output is present: