Get a task (with steps)
Unlike the listing, this carries the task's steps — every one by default, or the newest N with steps_limit, where steps_total reports the true count.
GET /tasks/{id}
curl --request GET \
--url https://{host}/api/tasks/{id} \
--header 'Authorization: Bearer <token>' \
--header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'import requests
url = "https://{host}/api/tasks/{id}"
headers = {
"Authorization": "Bearer <token>",
"X-Pinecone-Api-Version": "<x-pinecone-api-version>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: "GET", headers: {"Authorization": "Bearer <token>", "X-Pinecone-Api-Version": "<x-pinecone-api-version>"}};
fetch("https://{host}/api/tasks/{id}", options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{host}/api/tasks/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"X-Pinecone-Api-Version: <x-pinecone-api-version>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://{host}/api/tasks/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://{host}/api/tasks/{id}")
.header("Authorization", "Bearer <token>")
.header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
.asString();require 'uri'
require 'net/http'
url = URI("https://{host}/api/tasks/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Pinecone-Api-Version"] = '<x-pinecone-api-version>'
response = http.request(request)
puts response.read_body{
"id": "<string>",
"project_id": "<string>",
"context_id": "<string>",
"agent_id": "<string>",
"session_id": "<string>",
"created_by": "<string>",
"workflow": "<string>",
"state": "<string>",
"error": "<string>",
"input": {
"session_id": "<string>",
"query_id": "<string>",
"ask": "<string>",
"messages": [
{
"role": null,
"content": null
}
],
"models": [
"<string>"
],
"tools": [
"<string>"
],
"shape": {},
"instructions": "<string>",
"scope": [
"<string>"
],
"turn_timeout_seconds": 123,
"retrieval": {
"retrieval_only": true,
"pointers_only": true,
"chunks_only": true,
"artifacts_only": true,
"max_retrieved": 123,
"max_retrieved_chars": 123,
"compose": true,
"max_steps": 123,
"thinking_level": "<string>"
},
"comparison_group": "<string>"
},
"output": {
"status": "<string>",
"query_id": "<string>",
"answer": "<string>",
"output_json": {},
"citations": [
"<string>"
],
"latency_ms": 123,
"unknown_models": [
"<string>"
]
},
"steps": [
{
"step_id": "<string>",
"status": "<string>",
"type": "<string>",
"content": "<string>",
"commentary": "<string>",
"code": "<string>",
"result": "<string>",
"cum_input_tokens": 123,
"cum_output_tokens": 123,
"job_id": "<string>",
"path": "<string>"
}
],
"steps_total": 123,
"tokens_prompt": 123,
"tokens_completion": 123,
"runtime_seconds": 123,
"running_from": "<string>",
"timeout_seconds": 123,
"timeout_at": "<string>",
"archived_at": "<string>",
"created_at": "<string>",
"last_activity_at": "<string>",
"schedule": "<string>",
"scheduled_at": "<string>"
}{
"message": "<string>",
"code": "<string>"
}Authorizations
Section titled “Authorizations”AuthorizationstringrequiredSession token from POST /auth/login, sent as Authorization: Bearer <token>.
Headers
Section titled “Headers”X-Pinecone-Api-Version?stringDate-based contract version, echoed back on the same header. Omit for the default (2026-07); send unstable for the in-development surface. An unrecognized value is rejected with 400 unsupported_api_version.
Path Parameters
Section titled “Path Parameters”idstringrequiredTask id.
Query Parameters
Section titled “Query Parameters”steps_limit?integerReturn only this many trailing steps. Absent returns them all.
Required range: 0 <= x
Response
Section titled “Response”200 — The task
One task record — a single run of a workflow, owned by the project.
idstringrequiredTask id.
project_idstringrequiredThe Pinecone project that owns the task.
context_id?string | nullThe context the run acts on. Null for a task that belongs to no context.
agent_id?string | nullReserved. Null on every task this version serves.
session_id?string | nullSet for query turns
created_bystringrequiredPrincipal that started the run.
workflowstringrequiredThe canonical workflow name.
statestringrequiredWhere the run has got to. scheduled waits for its due time; starting and provisioning are a container being claimed and built; running is the work happening; stopping is a termination in progress. completed, cancelled and failed are terminal.
error?string | nullFailure detail. Set on a failed task.
inputobjectrequiredOne shape for the whole search family — the same payload is written whichever of them a turn resolves to.
Show child attributes
session_idstringrequiredThe session the turn runs in.
query_idstringrequiredThe turn this task serves.
askstringrequiredTitle fallback for the tasks UI; empty when the turn had no user message
messagesobject[]requiredThe conversation history handed to the runtime.
Show child attributes
rolestringrequiredWho sent it, e.g. user.
contentstringrequiredThe message text.
modelsstring[]requiredThe session's model fallback list, in preference order.
toolsstring[]requiredTool names the turn may call.
shapeobject | nullrequiredJSON Schema the answer must conform to. Null on a free-text turn.
instructionsstring | nullrequiredThe session's system prompt. Null when none was pinned.
scopestring[]requiredContext ids the turn searches.
turn_timeout_secondsintegerrequiredRuntime budget for this one turn.
retrieval?objectThe turn's retrieval controls.
Show child attributes
retrieval_onlyboolean | nullrequiredSkip synthesis and return the hits. Null where the caller omitted it.
pointers_onlyboolean | nullrequiredSkip synthesis and return pointers only. Null where the caller omitted it.
chunks_onlyboolean | nullrequiredNarrow retrieval to chunks. Null where the caller omitted it.
artifacts_onlyboolean | nullrequiredNarrow retrieval to artifacts. Null where the caller omitted it.
max_retrievedinteger | nullrequiredCap on retrieved items. Null where the caller omitted it.
max_retrieved_charsinteger | nullrequiredCap on per-item text length. Null where the caller omitted it.
composeboolean | nullrequiredWhether to synthesize an answer. Null where the caller omitted it.
max_stepsinteger | nullrequiredCap on the agent's tool-loop steps. Null where the caller omitted it.
thinking_levelstring | nullrequiredReasoning depth. Null where the caller omitted it.
comparison_groupstring | nullrequiredThe Compare run this turn belongs to. Null on a normal single query.
output?objectWhat a finished search turn's task reports. The turn itself, with its steps and structured citations, is at GET /queries/query_id.
Show child attributes
statusstringrequiredHow the turn ended.
query_idstringrequiredThe turn this task answered.
answerstringrequiredThe answer text.
output_json?object | nullStructured answer when the turn carried a shape, or the hits on a retrieval-only turn. Absent otherwise.
citationsstring[]requiredCited source paths. The turn carries the structured form.
latency_msintegerrequiredWall time for the turn.
unknown_models?string[]Model selections dropped as unknown before dispatch, so a caller whose pin was silently ignored can see it. Absent when nothing was dropped.
stepsobject[]requiredPopulated only on GET /tasks/id. May be a trailing window when steps_limit was given, so read the count from steps_total rather than this array's length.
Show child attributes
step_idstringrequiredIdentifies the step within the task.
statusstringrequiredHow the step ended, e.g. running or completed.
type?stringWhat kind of step this is; the vocabulary is per-workflow.
content?stringThe step's reported text payload.
commentary?stringThe runtime's one-line account of what the step is doing.
code?stringRedacted tool input (search)
result?stringRedacted tool output (search)
cum_input_tokens?integerTask-to-date input tokens, including this step.
cum_output_tokens?integerTask-to-date output tokens, including this step.
job_id?stringIdentifier of the LlamaParse job doing the work.
path?stringSource path being parsed
steps_total?integerTrue number of recorded steps. Absent on a read that carries no steps.
tokens_promptintegerrequiredInput tokens the run has billed so far.
tokens_completionintegerrequiredOutput tokens the run has billed so far.
runtime_secondsintegerrequiredSeconds the container has been running.
running_from?string | nullWhen the container started. Null before it does.
timeout_seconds?integer | nullRuntime budget for this task. Null when it runs uncapped.
timeout_at?string | nullWhen the budget expires and the run is terminated.
archived_at?string | nullWhen the task's files were archived. Null while they are still live.
created_atstringrequiredWhen the task row was created.
last_activity_at?string | nullWhen the runtime last reported anything. Drives stall detection.
schedule?string | nullCron expression this run was scheduled from. Null for an on-demand run.
scheduled_at?string | nullWhen a scheduled task is due to start.
parent_task_id?string | nullThe task that spawned this one, as an optimize spawns its curates.
progress?objectCoarse run progress, written by the runtime. Absent on a task that reports none.
Show child attributes
phaseintegerrequired1-based index of the phase now running.
phasesintegerrequiredTotal phases this run expects.
labelstringrequiredWhat the current phase is doing.
pctnumberrequiredCompletion across the whole run, 0–100.
eta_seconds?integer | nullEstimated seconds remaining. Null when the run cannot estimate one.