Retrieve a turn

Retrieve a turn

curl --request GET \
  --url https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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

{
  "object": "turn",
  "id": "<string>",
  "session_id": "<string>",
  "status": "working",
  "created_at": 123,
  "started_at": 123,
  "completed_at": 123,
  "artifacts": "pending",
  "artifacts_skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ],
  "subagent_id": "<string>",
  "error": {}
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

GET

sessions

{session_id}

turns

{turn_id}

Retrieve a turn

curl --request GET \
  --url https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

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

fetch('https://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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://api.{domain}/v1/sessions/{session_id}/turns/{turn_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

{
  "object": "turn",
  "id": "<string>",
  "session_id": "<string>",
  "status": "working",
  "created_at": 123,
  "started_at": 123,
  "completed_at": 123,
  "artifacts": "pending",
  "artifacts_skipped": [
    {
      "path": "<string>",
      "reason": "<string>"
    }
  ],
  "subagent_id": "<string>",
  "error": {}
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "<string>",
    "request_id": "<string>"
  }
}

Authorizations

Authorization

string

header

required

A gbr_pat_ access token. Scopes are recorded on the token when it is minted.

Response

Retrieve one turn.

object

string

required

Always turn. Names the shape, so a value can be identified without knowing which call returned it.

Allowed value: "turn"

string

required

Ours. Quote it when reporting a problem with this turn.

session_id

string

required

The session this turn belongs to.

status

enum<string>

required

working covers everything before it settles, including a turn parked on a tool result from you — watch the session's requires_action for that, not this field. completed, failed and cancelled are settled; a settled turn never moves again.

Available options:

working,

completed,

failed,

cancelled

created_at

integer

required

Unix milliseconds, when the input was accepted.

started_at

integer | null

When the agent began. Null until it does — a turn is working from the moment it is accepted, including while it waits behind another one, so this is the only field that tells the two apart. queued was removed from status; this description still named it.

completed_at

integer | null

When it settled. Null until it has.

artifacts

enum<string> | null

Whether this turn's artifacts can be fetched yet. Publication runs after the turn settles, so an empty artifact list under pending means not yet, and under ready means the turn produced nothing. partial means publishing finished and left something behind — read artifacts_skipped for what and why.

Available options:

pending,

ready,

partial,

failed,

null

artifacts_skipped

object[]

Files publishing did not take, and why. Empty unless artifacts is partial. A file past the per-file ceiling, or one that did not fit in what the turn had left, is reported here rather than disappearing.

Show child attributes

subagent_id

string | null

Always null today; reserved for delegation.

error

object | null

Why it failed, when it did. Null otherwise.

Start here

Running a session

Guides

Client libraries

When things go wrong

API reference

About this API

Endpoints

Authorizations

Response