Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

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
curl --request GET \
  --url https://{host}/api/tasks/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'X-Pinecone-Api-Version: <x-pinecone-api-version>'
Python
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)
JavaScript
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
<?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;
}
Go
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))

}
Java
HttpResponse<String> response = Unirest.get("https://{host}/api/tasks/{id}")
  .header("Authorization", "Bearer <token>")
  .header("X-Pinecone-Api-Version", "<x-pinecone-api-version>")
  .asString();
Ruby
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
200
{
  "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>"
}
404
{
  "message": "<string>",
  "code": "<string>"
}
Authorizationstringrequired

Session token from POST /auth/login, sent as Authorization: Bearer <token>.

X-Pinecone-Api-Version?string

Date-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.

Typestring
Default2026-07
idstringrequired

Task id.

Typestring
steps_limit?integer

Return only this many trailing steps. Absent returns them all.

Required range: 0 <= x

Typeinteger

200 — The task

One task record — a single run of a workflow, owned by the project.

idstringrequired

Task id.

Typestring
project_idstringrequired

The Pinecone project that owns the task.

Typestring
context_id?string | null

The context the run acts on. Null for a task that belongs to no context.

Typestring | null
agent_id?string | null

Reserved. Null on every task this version serves.

Typestring | null
session_id?string | null

Set for query turns

Typestring | null
created_bystringrequired

Principal that started the run.

Typestring
workflowstringrequired

The canonical workflow name.

Typestring
statestringrequired

Where 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.

Typestring
error?string | null

Failure detail. Set on a failed task.

Typestring | null
inputobjectrequired

One shape for the whole search family — the same payload is written whichever of them a turn resolves to.

Typeobject
Show child attributes
session_idstringrequired

The session the turn runs in.

Typestring
query_idstringrequired

The turn this task serves.

Typestring
askstringrequired

Title fallback for the tasks UI; empty when the turn had no user message

Typestring
messagesobject[]required

The conversation history handed to the runtime.

Typeobject[]
Show child attributes
rolestringrequired

Who sent it, e.g. user.

Typestring
contentstringrequired

The message text.

Typestring
modelsstring[]required

The session's model fallback list, in preference order.

Typestring[]
toolsstring[]required

Tool names the turn may call.

Typestring[]
shapeobject | nullrequired

JSON Schema the answer must conform to. Null on a free-text turn.

Typeobject | null
instructionsstring | nullrequired

The session's system prompt. Null when none was pinned.

Typestring | null
scopestring[]required

Context ids the turn searches.

Typestring[]
turn_timeout_secondsintegerrequired

Runtime budget for this one turn.

Typeinteger
retrieval?object

The turn's retrieval controls.

Typeobject
Show child attributes
retrieval_onlyboolean | nullrequired

Skip synthesis and return the hits. Null where the caller omitted it.

Typeboolean | null
pointers_onlyboolean | nullrequired

Skip synthesis and return pointers only. Null where the caller omitted it.

Typeboolean | null
chunks_onlyboolean | nullrequired

Narrow retrieval to chunks. Null where the caller omitted it.

Typeboolean | null
artifacts_onlyboolean | nullrequired

Narrow retrieval to artifacts. Null where the caller omitted it.

Typeboolean | null
max_retrievedinteger | nullrequired

Cap on retrieved items. Null where the caller omitted it.

Typeinteger | null
max_retrieved_charsinteger | nullrequired

Cap on per-item text length. Null where the caller omitted it.

Typeinteger | null
composeboolean | nullrequired

Whether to synthesize an answer. Null where the caller omitted it.

Typeboolean | null
max_stepsinteger | nullrequired

Cap on the agent's tool-loop steps. Null where the caller omitted it.

Typeinteger | null
thinking_levelstring | nullrequired

Reasoning depth. Null where the caller omitted it.

Typestring | null
comparison_groupstring | nullrequired

The Compare run this turn belongs to. Null on a normal single query.

Typestring | null
output?object

What a finished search turn's task reports. The turn itself, with its steps and structured citations, is at GET /queries/query_id.

Typeobject
Show child attributes
statusstringrequired

How the turn ended.

Typestring
query_idstringrequired

The turn this task answered.

Typestring
answerstringrequired

The answer text.

Typestring
output_json?object | null

Structured answer when the turn carried a shape, or the hits on a retrieval-only turn. Absent otherwise.

Typeobject | null
citationsstring[]required

Cited source paths. The turn carries the structured form.

Typestring[]
latency_msintegerrequired

Wall time for the turn.

Typeinteger
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.

Typestring[]
stepsobject[]required

Populated 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.

Typeobject[]
Show child attributes
step_idstringrequired

Identifies the step within the task.

Typestring
statusstringrequired

How the step ended, e.g. running or completed.

Typestring
type?string

What kind of step this is; the vocabulary is per-workflow.

Typestring
content?string

The step's reported text payload.

Typestring
commentary?string

The runtime's one-line account of what the step is doing.

Typestring
code?string

Redacted tool input (search)

Typestring
result?string

Redacted tool output (search)

Typestring
cum_input_tokens?integer

Task-to-date input tokens, including this step.

Typeinteger
cum_output_tokens?integer

Task-to-date output tokens, including this step.

Typeinteger
job_id?string

Identifier of the LlamaParse job doing the work.

Typestring
path?string

Source path being parsed

Typestring
steps_total?integer

True number of recorded steps. Absent on a read that carries no steps.

Typeinteger
tokens_promptintegerrequired

Input tokens the run has billed so far.

Typeinteger
tokens_completionintegerrequired

Output tokens the run has billed so far.

Typeinteger
runtime_secondsintegerrequired

Seconds the container has been running.

Typeinteger
running_from?string | null

When the container started. Null before it does.

Typestring | null
timeout_seconds?integer | null

Runtime budget for this task. Null when it runs uncapped.

Typeinteger | null
timeout_at?string | null

When the budget expires and the run is terminated.

Typestring | null
archived_at?string | null

When the task's files were archived. Null while they are still live.

Typestring | null
created_atstringrequired

When the task row was created.

Typestring
last_activity_at?string | null

When the runtime last reported anything. Drives stall detection.

Typestring | null
schedule?string | null

Cron expression this run was scheduled from. Null for an on-demand run.

Typestring | null
scheduled_at?string | null

When a scheduled task is due to start.

Typestring | null
parent_task_id?string | null

The task that spawned this one, as an optimize spawns its curates.

Typestring | null
progress?object

Coarse run progress, written by the runtime. Absent on a task that reports none.

Typeobject
Show child attributes
phaseintegerrequired

1-based index of the phase now running.

Typeinteger
phasesintegerrequired

Total phases this run expects.

Typeinteger
labelstringrequired

What the current phase is doing.

Typestring
pctnumberrequired

Completion across the whole run, 0–100.

Typenumber
eta_seconds?integer | null

Estimated seconds remaining. Null when the run cannot estimate one.

Typeinteger | null
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu