Retrieve an agent
curl --request GET \
--url https://api.{domain}/v1/agents/{agent_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.{domain}/v1/agents/{agent_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/agents/{agent_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/agents/{agent_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/agents/{agent_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/agents/{agent_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{domain}/v1/agents/{agent_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": "agent",
"id": "<string>",
"name": "<string>",
"model": "<string>",
"model_credential_id": "<string>",
"instructions": "<string>",
"tools": [
{
"type": "mcp",
"name": "<string>",
"url": "<string>",
"command": "<string>",
"args": [
"<string>"
],
"allowed_tools": [
"<string>"
],
"required": true,
"redacted": [
"<string>"
],
"description": "<string>",
"parameters": {},
"timeout_seconds": 123
}
],
"text": {},
"created_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 an agent
Retrieve one agent.
GET
/
v1
/
agents
/
{agent_id}
Retrieve an agent
curl --request GET \
--url https://api.{domain}/v1/agents/{agent_id} \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.{domain}/v1/agents/{agent_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/agents/{agent_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/agents/{agent_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/agents/{agent_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/agents/{agent_id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.{domain}/v1/agents/{agent_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": "agent",
"id": "<string>",
"name": "<string>",
"model": "<string>",
"model_credential_id": "<string>",
"instructions": "<string>",
"tools": [
{
"type": "mcp",
"name": "<string>",
"url": "<string>",
"command": "<string>",
"args": [
"<string>"
],
"allowed_tools": [
"<string>"
],
"required": true,
"redacted": [
"<string>"
],
"description": "<string>",
"parameters": {},
"timeout_seconds": 123
}
],
"text": {},
"created_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 agent.
Always agent. Names the shape, so a value can be identified without knowing which call returned it.
Allowed value:
"agent"Ours. Pass it as agent.id when creating a session.
Yours, for recognising it. Not an identifier.
The model sessions from this agent run on, unless they override it.
The connection to run on. Null uses the organization's default.
Standing instructions given to every session started from this agent.
Maximum string length:
32000Tools every session started from this agent gets, unless it replaces them. Secrets are withheld — see redacted on an entry.
Show child attributes
Show child attributes
Output shaping copied into every session started from this agent.
Unix milliseconds.