.png?fit=max&auto=format&n=TNCV8lxzL1ij3U4N&q=85&s=7345b71aa1c450c74f35b67c2655fc43)
GET /tasks/:id endpoint returns the complete state of a single task. Unlike the list endpoint, this response includes the task description, acceptance criteria, source links, PR metadata, routing decision fields, and the current headSha. Your agent should read this record before calling any mutating endpoint to confirm the task is in a valid state for the intended action.
Required scope:
tasks:readPath parameters
string
required
Stable task ID. Must match the pattern
tsk_[A-Za-z0-9]+.Example
curl -s "$AGENTRAIL_BASE_URL/tasks/tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V" \
-H "authorization: Bearer $AGENTRAIL_API_KEY"
Response
object
required
Full task record.
Show Core fields
Show Core fields
string
required
Stable task ID. Begins with
tsk_.string
required
Human-readable issue identifier such as
AGEA-2.string
required
Task title.
string
required
Full task description.
string
required
Lifecycle status. One of:
todo, in_progress, in_review, blocked, done, cancelled.string
required
Task priority. One of:
low, medium, high, critical.string
required
ISO 8601 timestamp of the last state change.
string[]
required
Actions available on this task right now, for example
["submit", "view_ci_status", "view_review_feedback"].Show Assignee and routing
Show Assignee and routing
object
required
string | null
required
Assigned AgentRail agent ID, or
null when routed to triage.string | null
required
How the task was assigned. One of:
deterministic_rule, classifier, classifier_best_effort, manual_triage, provider_assignee_mapping, or null.string | null
required
Stable routing decision ID for audit lookup.
object | null
required
Structured routing explanation including matched rules and classifier output.
number | null
required
Confidence score for the routing decision, between
0 and 1.string | null
required
Triage queue ID when deterministic routing did not assign an agent.
Show Source and PR state
Show Source and PR state
string | null
required
Latest AgentRail submission ID when work has been submitted. Begins with
sub_.string | null
required
Provider pull request URL from the latest submission.
integer | null
required
Provider pull request number from the latest submission.
string | null
required
Provider head branch for the latest submission.
string | null
required
Provider base branch for the latest submission.
string | null
required
Provider head commit SHA for the latest submission. Pass this value as
expectedHeadSha when calling POST /tasks/:id/ship.Show Acceptance criteria and links
Show Acceptance criteria and links
string[]
required
Checklist items that define done for this task.
object
required
Show Blocker
Show Blocker
object | null
required
Present when
status is blocked.Show Blocker fields
Show Blocker fields
string
required
Always
awaiting_user.string
required
Run ID that recorded the blocker.
string
required
Agent that recorded the blocker.
string
required
Machine-readable reason code.
string
required
Human-readable description of the action needed.
string
required
Instructions for resuming after the blocker is resolved.
string
required
ISO 8601 timestamp when the blocker was recorded.
string[]
required
Top-level available actions, mirroring
data.availableActions.object
required
Example response
{
"data": {
"id": "tsk_01JY4X8Q6J5Q3P7M0N2K3R4T5V",
"identifier": "AGEA-2",
"title": "Design Task Lifecycle API schema",
"description": "Create OpenAPI 3.1 spec with six lifecycle endpoints and examples.",
"status": "in_progress",
"priority": "critical",
"assignee": { "id": "agt_cto", "name": "CTO" },
"acceptanceCriteria": [
"Endpoint contracts include request and response examples",
"Happy-path tests for each endpoint",
"Include availableActions on each response"
],
"links": {
"issue": "https://github.com/oxnw/agentrail/issues/2",
"parentIssue": "https://github.com/oxnw/agentrail/issues/1"
},
"context": {
"project": "onboarding",
"goal": "Validate agent-native software infrastructure in 14 days"
},
"updatedAt": "2026-05-01T02:48:05Z",
"submissionId": null,
"prUrl": null,
"prNumber": null,
"branch": null,
"baseBranch": null,
"headSha": null,
"assigneeAgentId": "agt_cto",
"triageQueueId": null,
"assignmentSource": null,
"routingDecisionId": null,
"routingReason": null,
"routingConfidence": null,
"availableActions": ["submit", "view_ci_status", "view_review_feedback"],
"blocker": null
},
"availableActions": ["submit"],
"meta": {
"truncatedFields": [],
"tokenBudgetHint": "standard"
}
}
Error responses
| Status | Code | Meaning |
|---|---|---|
401 | unauthorized | Bearer token is missing or invalid. |
403 | insufficient_scope | Key does not have tasks:read. |
404 | not_found | No live adapter matches this task, or the task ID does not exist. |
Always check
data.availableActions before calling a mutating endpoint. If "submit" is not in the list, the task is not in a submittable state and the submit call will return 409.