Schemas
Session
An agent session: one conversation with an agent, from trigger to terminal state.
An agent session: one conversation with an agent, from trigger to
terminal state. Returned by GET /sessions/{id} and carried by the
session stream's session/snapshot frames — REST and stream never
disagree about what a session looks like.
Example
{
"attribution": {
"id": "string",
"type": "github_user",
"user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"budget": {
"cents": 0,
"source": "system"
},
"client_version": "string",
"config_id": "string",
"config_override": {},
"context_repository": "string",
"cost": {
"fee": 0,
"llm": 0,
"sandbox_cpu": 0,
"sandbox_memory": 0,
"total": 0
},
"created_at": "2026-01-01T00:00:00Z",
"default_resolution": "repo_default",
"exit_status": "completed",
"harness": "claude_code",
"id": "string",
"last_activity_at": "2026-01-01T00:00:00Z",
"last_message_at": "2026-01-01T00:00:00Z",
"live_summary": "string",
"metadata": {},
"output_prs": [
{
"gh_pr_id": 0,
"number": 0,
"repo_full_name": "string",
"title": "string",
"url": "string"
}
],
"parent": {
"kind": "continuation",
"replayed_from_session_id": "string",
"session_id": "string"
},
"prompt": "string",
"prompting": {
"blocked_reason": "mention_surface",
"detail": "string",
"enabled": false,
"surface_name": "string"
},
"sandbox_id": "string",
"session_key": "string",
"session_state": "idle",
"source": "react",
"status": "scheduled",
"status_reason": "string",
"stopped": {
"at": "2026-01-01T00:00:00Z",
"by": 0,
"by_user": {
"avatar_url": "string",
"id": 0,
"login": "string",
"type": "User"
}
},
"surface": {
"run": "scheduled",
"session": "alive",
"status": "string"
},
"tokens": {
"cache_creation": 0,
"cache_read": 0,
"input": 0,
"model": "",
"output": 0,
"total": 0
},
"updated_at": "2026-01-01T00:00:00Z",
"webhook_id": "string",
"webhook_type": "github.issue"
}Schema
Every nested object is inlined, so this is a standalone JSON Schema document.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Session",
"properties": {
"attribution": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"type": {
"anyOf": [
{
"enum": [
"github_user",
"linear_user",
"slack_user",
"api_key"
],
"type": "string"
},
{
"type": "null"
}
]
},
"user": {
"anyOf": [
{
"properties": {
"avatar_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"login": {
"type": "string"
},
"type": {
"enum": [
"User",
"Organization",
"Bot",
"Mannequin"
],
"type": "string"
}
},
"required": [
"id",
"login",
"type",
"avatar_url"
],
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"budget": {
"properties": {
"cents": {
"default": 0,
"type": "integer"
},
"source": {
"enum": [
"system",
"account",
"config",
"run"
],
"type": "string"
}
},
"type": "object"
},
"client_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"config_override": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
]
},
"context_repository": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"cost": {
"properties": {
"fee": {
"default": 0,
"type": "integer"
},
"llm": {
"default": 0,
"type": "integer"
},
"sandbox_cpu": {
"default": 0,
"type": "integer"
},
"sandbox_memory": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"created_at": {
"format": "date-time",
"type": "string"
},
"default_resolution": {
"anyOf": [
{
"enum": [
"repo_default",
"account_default",
"none"
],
"type": "string"
},
{
"type": "null"
}
]
},
"exit_status": {
"anyOf": [
{
"enum": [
"completed",
"budget_hit",
"payment_required",
"tool_call_failed",
"lifecycle_hook_failed",
"missing_repo_access",
"missing_token_permissions",
"missing_sandbox_variables",
"cancelled",
"interrupted",
"error",
"stopped"
],
"type": "string"
},
{
"type": "null"
}
]
},
"harness": {
"enum": [
"claude_code",
"codex"
],
"type": "string"
},
"id": {
"type": "string"
},
"last_activity_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"last_message_at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"live_summary": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"default": {},
"type": "object"
},
"output_prs": {
"anyOf": [
{
"items": {
"properties": {
"gh_pr_id": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"number": {
"type": "integer"
},
"repo_full_name": {
"type": "string"
},
"title": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"url": {
"type": "string"
}
},
"required": [
"repo_full_name",
"number",
"url"
],
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
]
},
"parent": {
"properties": {
"kind": {
"anyOf": [
{
"enum": [
"continuation",
"handoff",
"resume"
],
"type": "string"
},
{
"type": "null"
}
]
},
"replayed_from_session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"prompt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"prompting": {
"properties": {
"blocked_reason": {
"anyOf": [
{
"enum": [
"mention_surface",
"ephemeral_trigger",
"non_interactive",
"harness_single_turn",
"closed",
"laptop"
],
"type": "string"
},
{
"type": "null"
}
]
},
"detail": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"enabled": {
"type": "boolean"
},
"surface_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"enabled"
],
"type": "object"
},
"sandbox_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_key": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"session_state": {
"anyOf": [
{
"enum": [
"idle",
"running",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"source": {
"enum": [
"react",
"manual",
"api",
"cli",
"mention",
"cron",
"laptop"
],
"type": "string"
},
"status": {
"enum": [
"scheduled",
"creating_sandbox",
"running",
"retrying",
"completed",
"error",
"cancelled",
"stopped"
],
"type": "string"
},
"status_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"stopped": {
"properties": {
"at": {
"anyOf": [
{
"format": "date-time",
"type": "string"
},
{
"type": "null"
}
]
},
"by": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"by_user": {
"anyOf": [
{
"properties": {
"avatar_url": {
"type": "string"
},
"id": {
"type": "integer"
},
"login": {
"type": "string"
},
"type": {
"enum": [
"User",
"Organization",
"Bot",
"Mannequin"
],
"type": "string"
}
},
"required": [
"id",
"login",
"type",
"avatar_url"
],
"type": "object"
},
{
"type": "null"
}
]
}
},
"type": "object"
},
"surface": {
"anyOf": [
{
"properties": {
"run": {
"anyOf": [
{
"enum": [
"scheduled",
"starting",
"working",
"waiting",
"done",
"failed",
"stopped",
"cancelled",
"retrying"
],
"type": "string"
},
{
"type": "null"
}
]
},
"session": {
"anyOf": [
{
"enum": [
"alive",
"sleeping",
"closed"
],
"type": "string"
},
{
"type": "null"
}
]
},
"status": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"session",
"run",
"status"
],
"type": "object"
},
{
"type": "null"
}
]
},
"tokens": {
"properties": {
"cache_creation": {
"default": 0,
"type": "integer"
},
"cache_read": {
"default": 0,
"type": "integer"
},
"input": {
"default": 0,
"type": "integer"
},
"model": {
"default": "",
"type": "string"
},
"output": {
"default": 0,
"type": "integer"
},
"total": {
"default": 0,
"type": "integer"
}
},
"type": "object"
},
"updated_at": {
"format": "date-time",
"type": "string"
},
"webhook_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"webhook_type": {
"anyOf": [
{
"enum": [
"github.issue",
"github.issue_comment",
"github.push",
"github.pull_request",
"github.pull_request_comment",
"github.pull_request_review",
"github.pull_request_review_comment",
"slack.app_mention",
"slack.message",
"slack.channel_created",
"linear.issue",
"linear.issue_comment",
"sentry.event_alert",
"sentry.metric_alert",
"user.message"
],
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"created_at",
"updated_at",
"harness",
"source",
"status",
"prompting"
],
"type": "object"
}