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))
}HttpResponse<String> response = Unirest.get("https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id}")
.header("Authorization", "Bearer <token>")
.asString();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>"
}
}Retrieve a turn
Retrieve one 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))
}HttpResponse<String> response = Unirest.get("https://api.{domain}/v1/sessions/{session_id}/turns/{turn_id}")
.header("Authorization", "Bearer <token>")
.asString();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
A gbr_pat_ access token. Scopes are recorded on the token when it is minted.
Response
Retrieve one turn.
Always turn. Names the shape, so a value can be identified without knowing which call returned it.
"turn"Ours. Quote it when reporting a problem with this turn.
The session this turn belongs to.
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.
working, completed, failed, cancelled Unix milliseconds, when the input was accepted.
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.
When it settled. Null until it has.
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.
pending, ready, partial, failed, null 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
Show child attributes
Always null today; reserved for delegation.
Why it failed, when it did. Null otherwise.