Get Session

GET/v1/agents/sessions/{session_id}

Read a Session. Execution status is read live, so poll this endpoint or use the event stream to follow progress.

Path parameters

stringsession_idrequired

Session ID (ses_ prefix).

Session object

Returned by create, get, update, rename, archive, and unarchive.

stringidrequired

Session ID with the ses_ prefix.

stringstatusrequired

Execution status: idle, in_progress, or failed. requires_action is not supported yet and surfaces as 502 executor_contract_error.

stringlifecycle_statusrequired

active or archived. Archived Sessions reject input.

object · nullfailurerequired

Public failure with code, message, action, and optional retryable.

string · integer · stringagent_id · agent_version · modelrequired

Frozen Agent version and effective model.

object · object | nullagent · usagerequired

OpenAI-shaped snapshot of the effective Agent configuration, and token usage (null until a turn reports usage).

Optional<string · null>source · source_id

Origin of the Session. Sessions created with POST /v1/agents/sessions report direct and a null source_id.

integerrow_versionrequired

Compare-and-set token for rename, archive, and unarchive.

curl -X GET https://api.sandbase.ai/v1/agents/sessions/ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83 \
  -H "Authorization: Bearer $SANDBASE_API_KEY"

Response200 OK

{
  "id": "ses_5b0e7c3a-91d2-5f4e-8a6b-2c9d4e1f7a83",
  "object": "agent.session",
  "agent": {
    "id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
    "name": "Research assistant",
    "model": "deepseek/deepseek-v4-flash",
    "instructions": "Answer with cited sources.",
    "multi_agent": {
      "enabled": false,
      "max_concurrent_subagents": null
    },
    "reasoning": {
      "effort": null,
      "summary": null
    },
    "service_tier": "auto",
    "text": {
      "format": {
        "type": "text"
      },
      "verbosity": "medium"
    },
    "tools": []
  },
  "agent_id": "agt_8c1f2b9e-3d4a-4f6b-9c2e-1a7d5e3b4c60",
  "agent_version": 1,
  "title": "Market scan",
  "model": "deepseek/deepseek-v4-flash",
  "environment": {
    "id": "env_…",
    "type": "openai_hosted",
    "capability_directories": [],
    "files": [],
    "network": {
      "access": "enabled",
      "allowed_domains": []
    },
    "packages": {
      "npm": [],
      "python": [],
      "system": []
    },
    "plugins": [],
    "skills": []
  },
  "metadata": {},
  "status": "in_progress",
  "lifecycle_status": "active",
  "sync_status": "ready",
  "execution_status": "in_progress",
  "failure": null,
  "row_version": 1,
  "required_actions": [],
  "vault_ids": [],
  "usage": null,
  "created_at": 1791273600,
  "last_active_at": 1791273600,
  "updated_at": 1791273600,
  "archived_at": null,
  "source": "direct",
  "source_id": null
}