Get a task (with steps)

curl --request GET \
  --url https://{host}/api/tasks/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "project_id": "<string>",
  "created_by": "<string>",
  "workflow": "<string>",
  "state": "<string>",
  "input": {
    "session_id": "<string>",
    "query_id": "<string>",
    "ask": "<string>",
    "messages": [
      {
        "role": "<string>",
        "content": "<string>"
      }
    ],
    "models": [
      "<string>"
    ],
    "tools": [
      "<string>"
    ],
    "shape": {},
    "instructions": "<string>",
    "scope": [
      "<string>"
    ],
    "turn_timeout_seconds": 123,
    "comparison_group": "<string>",
    "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>"
    }
  },
  "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>"
    }
  ],
  "tokens_prompt": 123,
  "tokens_completion": 123,
  "runtime_seconds": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "context_id": "<string>",
  "agent_id": "<string>",
  "session_id": "<string>",
  "error": "<string>",
  "output": {
    "status": "<string>",
    "query_id": "<string>",
    "answer": "<string>",
    "citations": [
      "<string>"
    ],
    "latency_ms": 123,
    "output_json": {},
    "unknown_models": [
      "<string>"
    ]
  },
  "steps_total": 123,
  "running_from": "2023-11-07T05:31:56Z",
  "timeout_seconds": 123,
  "timeout_at": "2023-11-07T05:31:56Z",
  "archived_at": "2023-11-07T05:31:56Z",
  "last_activity_at": "2023-11-07T05:31:56Z",
  "schedule": "<string>",
  "scheduled_at": "2023-11-07T05:31:56Z",
  "parent_task_id": "<string>",
  "progress": {
    "phase": 123,
    "phases": 123,
    "label": "<string>",
    "pct": 123,
    "eta_seconds": 123
  }
}

{
  "message": "<string>",
  "code": "<string>"
}

GET

tasks

{id}

Get a task (with steps)

curl --request GET \
  --url https://{host}/api/tasks/{id} \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$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>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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>'

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "project_id": "<string>",
  "created_by": "<string>",
  "workflow": "<string>",
  "state": "<string>",
  "input": {
    "session_id": "<string>",
    "query_id": "<string>",
    "ask": "<string>",
    "messages": [
      {
        "role": "<string>",
        "content": "<string>"
      }
    ],
    "models": [
      "<string>"
    ],
    "tools": [
      "<string>"
    ],
    "shape": {},
    "instructions": "<string>",
    "scope": [
      "<string>"
    ],
    "turn_timeout_seconds": 123,
    "comparison_group": "<string>",
    "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>"
    }
  },
  "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>"
    }
  ],
  "tokens_prompt": 123,
  "tokens_completion": 123,
  "runtime_seconds": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "context_id": "<string>",
  "agent_id": "<string>",
  "session_id": "<string>",
  "error": "<string>",
  "output": {
    "status": "<string>",
    "query_id": "<string>",
    "answer": "<string>",
    "citations": [
      "<string>"
    ],
    "latency_ms": 123,
    "output_json": {},
    "unknown_models": [
      "<string>"
    ]
  },
  "steps_total": 123,
  "running_from": "2023-11-07T05:31:56Z",
  "timeout_seconds": 123,
  "timeout_at": "2023-11-07T05:31:56Z",
  "archived_at": "2023-11-07T05:31:56Z",
  "last_activity_at": "2023-11-07T05:31:56Z",
  "schedule": "<string>",
  "scheduled_at": "2023-11-07T05:31:56Z",
  "parent_task_id": "<string>",
  "progress": {
    "phase": 123,
    "phases": 123,
    "label": "<string>",
    "pct": 123,
    "eta_seconds": 123
  }
}

{
  "message": "<string>",
  "code": "<string>"
}

Authorizations

Authorization

string

header

required

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

Headers

X-Pinecone-Api-Version

string

default:2026-07

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.

Path Parameters

string

required

Task id.

Query Parameters

steps_limit

integer

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

Required range: x >= 0

Response

The task

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

string

required

Task id.

project_id

string

required

The Pinecone project that owns the task.

created_by

string

required

Principal that started the run.

workflow

string

required

The canonical workflow name.

state

string

required

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.

input

Search / search_cc / search_rag / work · object

required

A task's per-workflow input. It carries no discriminant of its own — the sibling workflow field selects the shape.

Show child attributes

steps

object[]

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.

Show child attributes

tokens_prompt

integer<int64>

required

Input tokens the run has billed so far.

tokens_completion

integer<int64>

required

Output tokens the run has billed so far.

runtime_seconds

integer<int64>

required

Seconds the container has been running.

created_at

string<date-time>

required

When the task row was created.

context_id

string | null

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

agent_id

string | null

Reserved. Null on every task this version serves.

session_id

string | null

Set for query turns

error

string | null

Failure detail. Set on a failed task.

output

Search / search_rag completed · object

A task's reported output. Every workflow reports a different per-state shape, matched to a named variant only when its key set is exactly that variant's; anything else is preserved as stored. Treat this union as open. Null until the run reports anything.

Show child attributes

steps_total

integer<int64>

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

running_from

string<date-time> | null

When the container started. Null before it does.

timeout_seconds

integer | null

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

timeout_at

string<date-time> | null

When the budget expires and the run is terminated.

archived_at

string<date-time> | null

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

last_activity_at

string<date-time> | null

When the runtime last reported anything. Drives stall detection.

schedule

string | null

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

scheduled_at

string<date-time> | null

When a scheduled task is due to start.

parent_task_id

string | null

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

progress

object

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

Show child attributes

APIs

Control plane

Data plane

Get a task (with steps)

Authorizations

Headers

Path Parameters

Query Parameters

Response