Retrieve a session
curl --request GET \
--url https://api.{domain}/v1/sessions/{session_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.{domain}/v1/sessions/{session_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}', 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}",
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}"
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}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{domain}/v1/sessions/{session_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": "session",
"id": "<string>",
"status": "idle",
"created_at": 123,
"updated_at": 123,
"agent": {
"id": "<string>",
"model": "<string>",
"model_credential_id": "<string>",
"approval_mode": "<string>",
"instructions": "<string>",
"permission_rules": [
{}
],
"tools": [
{}
]
},
"environment": {
"type": "sandbox",
"state": "unknown",
"workspace_directory": "<string>",
"repo": {
"full_name": "<string>",
"branch": "<string>",
"clone_error": "<string>"
}
},
"preview": {
"url": "<string>",
"port": 123,
"published_url": "<string>"
},
"title": "<string>",
"source": "api",
"created_by_token": "<string>",
"required_actions": [
{
"type": "function_call",
"turn_id": "<string>",
"call_id": "<string>",
"name": "<string>",
"arguments": "<unknown>",
"created_at": 123,
"expires_at": 123
}
]
}{
"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>"
}
}API Reference
Retrieve a session
Retrieve one session.
GET
/
v1
/
sessions
/
{session_id}
Retrieve a session
curl --request GET \
--url https://api.{domain}/v1/sessions/{session_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.{domain}/v1/sessions/{session_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}', 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}",
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}"
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}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{domain}/v1/sessions/{session_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": "session",
"id": "<string>",
"status": "idle",
"created_at": 123,
"updated_at": 123,
"agent": {
"id": "<string>",
"model": "<string>",
"model_credential_id": "<string>",
"approval_mode": "<string>",
"instructions": "<string>",
"permission_rules": [
{}
],
"tools": [
{}
]
},
"environment": {
"type": "sandbox",
"state": "unknown",
"workspace_directory": "<string>",
"repo": {
"full_name": "<string>",
"branch": "<string>",
"clone_error": "<string>"
}
},
"preview": {
"url": "<string>",
"port": 123,
"published_url": "<string>"
},
"title": "<string>",
"source": "api",
"created_by_token": "<string>",
"required_actions": [
{
"type": "function_call",
"turn_id": "<string>",
"call_id": "<string>",
"name": "<string>",
"arguments": "<unknown>",
"created_at": 123,
"expires_at": 123
}
]
}{
"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 session.
Always session. Names the shape, so a value can be identified without knowing which call returned it.
Allowed value:
"session"Ours, not yours. Use metadata to carry your own identifier.
idle accepts input. working is running a turn. requires_action is waiting on you — see required_actions. failed is the last turn's outcome, not a dead session.
Available options:
idle, working, requires_action, failed Unix milliseconds.
Unix milliseconds. Moves on any change, including the workspace waking.
What is running, and how freely.
Show child attributes
Show child attributes
The workspace: its state, where the agent works, and the repository bound to it.
Show child attributes
Show child attributes
Addresses for whatever the agent is serving. See preview.md.
Show child attributes
Show child attributes
A label for people. Set it yourself; nothing derives one.
Which door created this session. Null on sessions predating the field.
Available options:
api, console, cli, null The id of the access token that created it — never its secret.
Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.
Show child attributes
Show child attributes