curl --request GET \
--url https://api.orion.file.ai/prod/v2/agent/sessions/{session_id} \
--header 'x-api-key: <api-key>'import requests
url = "https://api.orion.file.ai/prod/v2/agent/sessions/{session_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.orion.file.ai/prod/v2/agent/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.orion.file.ai/prod/v2/agent/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 => [
"x-api-key: <api-key>"
],
]);
$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.orion.file.ai/prod/v2/agent/sessions/{session_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
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.orion.file.ai/prod/v2/agent/sessions/{session_id}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orion.file.ai/prod/v2/agent/sessions/{session_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"session_id": "665f1c2e8a1b4c0012ab34cd",
"title": "New Chat",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"run_status": "COMPLETED",
"last_active_at": "2023-11-07T05:31:56Z",
"job_id": "sajob_9f2c1a4b7e8d4c1fa0b3"
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/not-found",
"title": "Not found",
"status": 404,
"detail": "No such session.",
"instance": "/v1/{route}",
"code": "NOT_FOUND",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [],
"message": "No such session.",
"error": "Not Found",
"statusCode": 404
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}Get an agent session
Returns one session and the status of its most recent run.
run_status is how you tell whether the session can take a turn: QUEUED and RUNNING mean a run is in flight and asking is a 409; every other value — including null, for a session that has never run — means it is free.
A run whose worker died sends no terminal event, so a run that stopped reporting is reconciled to STALE when you read the session. Reading it is therefore how a session stuck behind a dead run becomes usable again.
curl --request GET \
--url https://api.orion.file.ai/prod/v2/agent/sessions/{session_id} \
--header 'x-api-key: <api-key>'import requests
url = "https://api.orion.file.ai/prod/v2/agent/sessions/{session_id}"
headers = {"x-api-key": "<api-key>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {'x-api-key': '<api-key>'}};
fetch('https://api.orion.file.ai/prod/v2/agent/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.orion.file.ai/prod/v2/agent/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 => [
"x-api-key: <api-key>"
],
]);
$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.orion.file.ai/prod/v2/agent/sessions/{session_id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("x-api-key", "<api-key>")
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.orion.file.ai/prod/v2/agent/sessions/{session_id}")
.header("x-api-key", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.orion.file.ai/prod/v2/agent/sessions/{session_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"session_id": "665f1c2e8a1b4c0012ab34cd",
"title": "New Chat",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"run_status": "COMPLETED",
"last_active_at": "2023-11-07T05:31:56Z",
"job_id": "sajob_9f2c1a4b7e8d4c1fa0b3"
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/not-found",
"title": "Not found",
"status": 404,
"detail": "No such session.",
"instance": "/v1/{route}",
"code": "NOT_FOUND",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [],
"message": "No such session.",
"error": "Not Found",
"statusCode": 404
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}{
"type": "https://errors.file.ai/validation-failed",
"title": "Validation failed",
"status": 422,
"detail": "One or more fields are invalid.",
"instance": "/v1/files/upload",
"code": "VALIDATION_FAILED",
"requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
"errors": [
{
"code": "REQUIRED",
"detail": "must not be empty",
"pointer": "#/fileName",
"parameter": "limit"
}
],
"message": "Validation failed",
"error": "Unprocessable Entity",
"statusCode": 422,
"retryAfter": 42
}run_status means and how a session recovers from a run whose worker
died mid-turn.Authorizations
API key for authentication
Headers
Accepted for client uniformity but IGNORED on this endpoint. It has no side effects, and a retry can legitimately return different results, so replaying a cached response would hand back stale data. Every request executes fresh: no 24h window, no replay, no Idempotent-Replayed header, and no key-reuse 422.
Path Parameters
Session to read.
Response
The session.
Opaque session identifier used by the other agent routes.
"665f1c2e8a1b4c0012ab34cd"
The submitted title, or the placeholder the agent replaces when it names the session on its first turn.
"New Chat"
Status of this session's most recent run, or null if it has never run.
QUEUED and RUNNING mean a turn is in flight — asking again is a 409. COMPLETED, FAILED, STOPPED and STALE all mean the session is free. STALE is assigned on read when a run stopped reporting past its threshold, which is how a session recovers from a worker that died without sending a terminal event.
QUEUED, RUNNING, COMPLETED, FAILED, STOPPED, STALE "COMPLETED"
When a turn was last enqueued on this session.
Job handle for the most recent run, when it was started through this API. Null for a turn asked in the app.
"sajob_9f2c1a4b7e8d4c1fa0b3"