--- title: "Get Conversation" method: GET path: "/v1/agents/{agent_id}/gateway/conversations/{conversation_id}" tags: ["API v1", "Agents", "Agent Gateway (deprecated alias)"] deprecated: true --- # Get Conversation `GET /v1/agents/{agent_id}/gateway/conversations/{conversation_id}` ## Request - Base URL: `https://api.xpander.ai` (the document declares no server; this is the origin it was published from) - URL: `https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}` - Auth: API key in header `x-api-key` > **Deprecated.** Return the parent execution, activity thread, aggregate cost / token usage, and every sub-execution's (execution, activity, usage) triple. ## Path parameters - `agent_id` string, required - `conversation_id` string, required ## Response `200` Successful Response - ConversationResponse: Combined view of one chat conversation. `conversation_id` is the parent gateway execution id, which is also the activity-thread id. `execution`, `activity`, and `usage` can each be independently `None` when the upstream is unavailable — the route returns 404 only when BOTH `execution` AND `activity` are missing. `usage` at this root level is aggregated across the parent execution AND every entry in `sub_executions` (single upstream call to the `llm_usage:aggregate` endpoint). Per-sub usage is mirrored on each `SubExecutionResponse.usage` so clients don't have to fan-out. - `conversation_id` string, required - `execution` AgentExecution - `background_auth_eligible` boolean - `id` string, required - `agent_id` string, required - `organization_id` string, required - `input` AgentExecutionInputOutput, required - `text` string, nullable - `files` string[], nullable - `attachments` AttachmentRef[], nullable - `url` string, required - `name` string, nullable - `mime` string, nullable - `size` integer, nullable - `kind` 'image' | 'pdf' | 'document' | 'text' | 'audio' | 'video' | 'archive' | 'unknown': Coarse attachment class, resolved from mime/magic/extension. Mirrored in xpander-sdk (models/task.py + models/generic-adjacent); keep the members identical. - `sha256` string, nullable - `expires_at` string, nullable - `source` string, nullable - `transcript` string, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - `principal` Principal: Typed caller identity: who invoked the run and through which door. - `kind` 'user' | 'slack' | 'api_key' | 'system' | 'anonymous', required - `id` string, required - `email` string, nullable - `display_name` string, nullable - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `status` 'pending' | 'executing' | 'paused' | 'error' | 'failed' | 'completed' | 'stopped' - `internal_status` string, nullable - `last_executed_node_id` string, nullable - `agent_version` string, nullable - `created_at` string, date-time, required - `started_at` string, date-time, nullable - `paused_at` string, date-time, nullable - `finished_at` string, date-time, nullable - `result` string, nullable - `parent_execution` string, nullable - `conversation_id` string, nullable - `sub_executions` string[], nullable - `finished_sub_executions` string[], nullable - `should_update_parent` boolean, nullable - `is_manually_stopped` boolean, nullable - `is_background` boolean, nullable - `payload_extension` object, nullable - `hitl_request` HumanInTheLoopRequest: Model representing human-in-the-loop approval records for tasks. Attributes: wait_node_id (str): The id of the node that triggered this HITL. - `wait_node_id` string, required - `pending_eca_request` PendingECARequest - `connector_name` string, required - `auth_url` string, required - `pending_tool_approvals` PendingToolApproval[], nullable: Tool calls held for a person's approval on this execution; each names the request id a decision route takes. - `request_id` string, required - `tool_name` string, required - `tool_label` string - `summary` string, nullable - `gate_reason` 'per_tool' | 'connector_mutating' | 'connector_read_only' | 'credential_policy' | 'gated_command' | 'elicitation' - `created_at` string, date-time, nullable - `expires_at` string, date-time, nullable - `kind` 'approval' | 'elicitation' - `message` string, nullable - `requested_schema` object, nullable - `source` string, nullable - `worker_id` string, nullable - `additional_context` string, nullable - `instructions_override` string, nullable - `expected_output` string, nullable - `engagement_instructions` string, nullable - `output_format_instructions` string, nullable - `test_run_node_id` string, nullable - `is_orchestration` boolean, nullable - `is_gateway` boolean, nullable - `conversation_kind` 'direct' | 'gateway': direct: the head row never runs a model turn, every message is one task on the agent; gateway: a router-era head. - `is_app` boolean, nullable - `is_desktop` boolean, nullable - `device_id` string, nullable - `desktop_user_id` string, nullable - `verified_user_transport` string, nullable - `sub_tasks_mode` 'sync' | 'async' | 'auto' - `output_format` 'text' | 'markdown' | 'json' | 'voice' - `voice_id` string, nullable - `output_schema` object, nullable - `events_streaming` boolean, nullable - `used_mutating_tools` boolean, nullable - `is_continuous` boolean, nullable - `mcp_servers` object[], nullable - `triggering_agent_id` string, nullable - `title` string, nullable - `think_mode` 'default' | 'harder' - `disable_attachment_injection` boolean, nullable - `deep_planning` DeepPlanning - `enabled` boolean, nullable - `enforce` boolean, nullable - `started` boolean, nullable - `question_raised` boolean, nullable - `tasks` DeepPlanningItem[], nullable - `id` string, required - `title` string, required - `description` string, nullable - `input` unknown - `output` unknown - `tool_name` string, nullable - `completed` boolean, nullable - `must_deep_plan` boolean, nullable - `short_summary` string, nullable - `execution_attempts` integer, nullable - `user_tokens` object, nullable - `user_oidc_token` string, nullable - `return_metrics` boolean, nullable - `tokens` LLMTokens - `completion_tokens` integer, nullable - `prompt_tokens` integer, nullable - `total_tokens` integer, nullable - `cache_read_tokens` integer, nullable - `cache_write_tokens` integer, nullable - `llm_model_provider` string, nullable: Snapshot of the LLM provider used for this execution (request override or agent default at run time). - `llm_model_name` string, nullable: Snapshot of the LLM model name used for this execution (request override or agent default at run time). - `llm_reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh' - `execution_kind` 'turn' | 'resident': A turn ends when the CLI answers; a resident process stays Executing until the agent finishes it. - `harness_cli` 'claude-code' | 'codex' | 'opencode' | 'xpander': A CLI the harness container can run; chosen per conversation, never per agent. - `harness_cli_switches` HarnessCliSwitch[], nullable: Harness agents only: the conversation's CLI timeline, oldest first; the first entry is the CLI it started on, every later one a switch. - `cli` 'claude-code' | 'codex' | 'opencode' | 'xpander', required: A CLI the harness container can run; chosen per conversation, never per agent. - `at` string, date-time, required - `permission_mode` 'full' | 'gated' - `builtin_tools` object, nullable: Harness agents only: the resolved built-in tool sets this execution runs with, {"harness": {"enabled": bool}, "xpander": {"enabled": bool}}; inherited per half by later tasks of the conversation unless one names its own. - `tool_call_limit` integer, nullable: Max tool calls for this execution; unset leaves the agent's own ceiling in place. - `archived_at` string, date-time, nullable: When the conversation was archived; unset while it is live. - `archived_by` string, nullable: Who archived the conversation (user id), when it was. - `archived_by_agent_id` string, nullable: The agent that archived the conversation on its own, when one did; unset when a person archived it. - `deleted_at` string, date-time, nullable: When the user deleted the conversation; a deleted conversation never mirrors to history again and reads as not found. - `waiting_reason` string, nullable, required: Why a live resident process is waiting rather than working (`plan_limit`); None otherwise. - `resumes_at` string, date-time, nullable, required: When a waiting process resumes on its own (ISO), read from its booked wake; None otherwise. - `activity` AgentActivityThread - `id` string, required - `created_at` string, date-time, required - `messages` union[], required - union - AgentActivityThreadMessage - `id` string, required - `created_at` string, date-time, required - `role` 'user' | 'agent', required - `content` AgentActivityThreadMessageContent, required - `text` string, nullable - `files` string[], nullable - `attachments` AttachmentRef[], nullable - … - `segments` AgentActivityTextSegment[], nullable - … - `sub_execution_result` boolean, nullable - `is_steering` boolean, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `identity` MessageIdentity: Display identity stamped on events/messages produced under a skill. - `name` string, required: Display name shown on the bubble, e.g. Skill Builder. - `icon` string, nullable: Emoji or icon URL shown as the avatar. - `sequence` integer, nullable - `handed_back_to` HandedBackTo: The calling agent a delegated turn's final reply was returned to. - `agent_id` string, required - `agent_name` string, nullable - `conversation_id` string, required - AgentActivityThreadToolCall - `id` string, required - `created_at` string, date-time, required - `tool_name` string, required - `operation_id` string, nullable - `agent_id` string, nullable - `payload` unknown, required - `is_error` boolean, nullable - `reasoning` ToolCallRequestReasoning - `title` string, nullable - `description` string, nullable - `result` unknown - `plan_task_id` string, nullable - `approval_request_id` string, nullable - `parent_request_id` string, nullable - `credential` ToolCallCredential: Whose credential a connector tool call resolved - ids and names only, never a value. - `auth_mode` 'service' | 'user_authentication', required - `connection_id` string, nullable - `connection_name` string, nullable - `user_id` string, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - `sequence` integer, nullable - AgentActivityThreadReasoning - `id` string, required - `created_at` string, date-time, required - `type` 'think' | 'analyze', required - `title` string, required - `confidence` number, required - `thought` string, nullable - `sequence` integer, nullable - `action` string, nullable - `result` string, nullable - `analysis` string, nullable - `agent_id` string, nullable - `plan_task_id` string, nullable - AgentActivityThreadSubAgentTrigger - `id` string, required - `created_at` string, date-time, required - `agent_id` string, required - `query` string, nullable - `task_id` string, nullable - `result` string, nullable - `files` string[], nullable - `attachments` AttachmentRef[], nullable - `url` string, required - `name` string, nullable - `mime` string, nullable - `size` integer, nullable - `kind` 'image' | 'pdf' | 'document' | 'text' | 'audio' | 'video' | 'archive' | 'unknown': Coarse attachment class, resolved from mime/magic/extension. Mirrored in xpander-sdk (models/task.py + models/generic-adjacent); keep the members identical. - `sha256` string, nullable - `expires_at` string, nullable - `source` string, nullable - `transcript` string, nullable - `reasoning` ToolCallRequestReasoning, required - `title` string, nullable - `description` string, nullable - `plan_task_id` string, nullable - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `on_behalf_of` string, nullable - `on_behalf_of_email` string, nullable - `access_reason` string, nullable - AgentActivityThreadAuth - `type` 'not_supported' | 'login_required' | 'token_issue' | 'token_ready', required - `data` union, required - MCPOAuthGetTokenTokenReadyResponse - … - MCPOAuthGetTokenLoginRequiredResponse - … - MCPOAuthGetTokenGenericResponse - … - `id` string, required - `created_at` string, date-time, required - AgentActivityThreadPlanUpdate - `enabled` boolean, nullable - `enforce` boolean, nullable - `started` boolean, nullable - `question_raised` boolean, nullable - `tasks` DeepPlanningItem[], nullable - `id` string, required - `title` string, required - `description` string, nullable - `input` unknown - `output` unknown - `tool_name` string, nullable - `completed` boolean, nullable - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - AgentActivityThreadTaskCompactizationEvent - `id` string, required - `created_at` string, date-time, required - `type` 'retry' | 'summarization' | 'compaction_started' | 'compaction_progress' | 'manual_compaction' | 'emergency_compaction' | 'pre_retry_compaction' | 'compaction_error', required - `data` union, required - TaskCompactizationOutput - … - TaskCompactizationRetryEvent - … - TaskCompactizationStarted: Emitted when a compaction attempt begins. - … - TaskCompactizationProgress: Customer-facing progress update emitted during a running compaction. Designed for direct rendering: the UI should only need ``percent``, ``label`` and the optional ``detail`` line. Internal phase / timing / streaming metrics are intentionally NOT included in the wire payload. - … - TaskCompactizationError: Emitted when a compaction attempt fails. - … - AgentActivityThreadGatewayCreateExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'create_execution' - `created_execution_id` string, required - `query` string - `is_async` boolean, nullable - `ack_message` string - `target_agent_id` string, nullable - `target_agent_name` string, nullable - AgentActivityThreadGatewayAskExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_execution' - `created_execution_id` string, required - `new_input` string, required - `rejected` string, nullable - AgentActivityThreadGatewayStopExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'stop_execution' - `created_execution_id` string, required - AgentActivityThreadGatewayContinueExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'continue_execution' - `created_execution_id` string, required - `rejected` string, nullable - AgentActivityThreadGatewayGetExecutionsResult - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'get_executions_result' - `executions` AgentActivityThreadGatewayExecutionResultEntry[] - `created_execution_id` string, required - `status` string, nullable - `result` string, nullable - AgentActivityThreadGatewayAskUserQuestions - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_user_questions' - `questions` GatewayQuestion[] - `id` string, required: Stable id used to correlate the user's answer. - `text` string, required: The question itself, in the user's language. - `header` string: Short chip/label for the question card. - `options` GatewayQuestionOption[] - … - `allow_free_text` boolean: True → the user may type a custom answer (free-text or 'Other'). - `multi_select` boolean: True → more than one option may be selected. - `folded` boolean, nullable - `held_by_execution` string, nullable - AgentActivityThreadAskUserQuestionsAnswers: User-submitted answers to a prior ask_user_questions card. Persisted as its own activity entry (links to the question via `decision_id`) and replayed into the gateway LLM context as a user message. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `answers` GatewayAnswerItem[] - `question_id` string, required - `question_text` string - `header` string - `selected_options` GatewayQuestionOption[] - … - `free_text` string, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadProcessUpdate: A note the agent wrote for the person while its resident process ran (`tell_user`). - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `text` string, required - `kind` 'update' | 'milestone' | 'warning' - `segment` integer - `held_by_execution` string, nullable - `sequence` integer, nullable - AgentActivityThreadGatewaySuggestTool - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'suggest_tool' - `suggestions` GatewaySuggestedTool[] - `kind` 'action' | 'custom_function' | 'mcp' | 'agent' | 'workflow' | 'skill', required: Tool kind the suggestion / choice refers to (mirrors AddAgentToolRequest). - `name` string, required: User-facing tool / connector name. - `description` string - `logo` string, nullable - `connector_id` string, nullable - `using_built_in_auth` boolean - `connections` GatewayConnectorConnection[] - … - `mcp_id` string, nullable - `skill_name` string, nullable - `target_id` string, nullable - `transport` string, nullable - `auth_type` string, nullable - `url` string, nullable - `allow_custom_mcp` boolean - `folded` boolean, nullable - AgentActivityThreadToolSuggestionResolved: The user's resolved choice for a prior suggest_tool card. Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the attach itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `choice` ToolSuggestionChoice, required: The tool the user picked. For a connector, either reference an existing connection (connection_id) OR carry a new-connection payload (security + meta) the backend persists — OAuth token, API key, AWS creds, etc. - `kind` 'action' | 'custom_function' | 'mcp' | 'agent' | 'workflow' | 'skill', required: Tool kind the suggestion / choice refers to (mirrors AddAgentToolRequest). - `connector_id` string, nullable - `connection_id` string, nullable - `decision_id` string, nullable - `security` object, nullable - `name` string, nullable - `access_scope` string, nullable - `is_service_account` boolean, nullable - `headers` object, nullable - `mcp_id` string, nullable - `skill_name` string, nullable - `target_id` string, nullable - `url` string, nullable - `mcp_name` string, nullable - `transport` string, nullable - `auth_type` string, nullable - `api_key` string, nullable - `client_id` string, nullable - `client_secret` string, nullable - `additional_scopes` string[], nullable - `share_user_token_across_other_agents` boolean, nullable - `allowed_tools` string[], nullable - `tool_name` string - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadGatewayInviteMember - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'invite_member' - `email` string - `role` 'member' | 'admin' | 'super_admin' | 'viewer': Role for the invited teammate (maps to the invite-members edge fn payload). - `editable` boolean - AgentActivityThreadInviteMemberResolved: The user's resolved confirmation for a prior invite_member card. Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the invite itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `email` string, required - `role` 'member' | 'admin' | 'super_admin' | 'viewer': Role for the invited teammate (maps to the invite-members edge fn payload). - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadGatewayAdminChange: A staged admin change awaiting the requester's confirmation; the id is the change id. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'admin_change' - `change_id` string - `summary` string - `before` unknown - `after` unknown - `danger` boolean - `area` string - `tool` string - `verb` string - `expires_at` string, nullable - `manifest` object, nullable - `requested_by` string - `platform_url` string - AgentActivityThreadAdminChangeResolved: The requester's answer to a staged admin change (links via `decision_id`), so the card locks on reload. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `outcome` 'applied' | 'cancelled' | 'expired' | 'refused' | 'failed', required: How a staged admin change ended. - `title` string - `detail` string - `platform_url` string - `audit_url` string - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadGatewayAskForSecret - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_for_secret' - `secrets` RequiredSecret[] - `name` string, required: Env var name, e.g. AWS_ACCESS_KEY_ID. - `description` string: What the secret is for (shown under the input). - `secret` boolean: Mask the input (true for secrets, false for plain config). - `required` boolean: Whether the value must be filled before submitting. - `target_agent_id` string, nullable - `target_agent_name` string, nullable - `overwrite` boolean - AgentActivityThreadAskForSecretResolved: The user's resolution of a prior ask_for_secret card (names only, no values). Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the save itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `names` string[] - `declined` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadToolApproval: A tool call held until a person answers, rendered as an interactive card. Carries no arguments: the payload lives on the approval request, and a card the whole conversation can see must not become the place a call's inputs are published. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'tool_approval' - `request_id` string, required - `tool_label` string - `intent` string - `payload_summary` string - `statement_kind` string, nullable - `statement_target` string, nullable - `requester_name` string - `requester_user_id` string - `agent_name` string - `approver_user_ids` string[] - `approver_group_ids` string[] - `kind` string, nullable - `server` string, nullable - `message` string, nullable - `requested_schema` object, nullable - AgentActivityThreadToolApprovalResolved: The answer to a prior approval card (links via `request_id`), so it locks on reload. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `request_id` string, required - `approved` boolean - `decided_by_name` string - `decided_via` string - `note` string - `withdrawn` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadConfirmResolved: The answer to a prior confirmation card (links via `decision_id`), stamped before the resume so the card is single-use. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `approved` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadMcpRegistered: Terminal record of the MCP registration wizard (links via `decision_id`). Persisted when the enable step resolves so the wizard card locks on reload; the registry create + attach happen in the chat-backend routes. No secrets. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `registry_id` string - `name` string - `url` string - `enabled_agent_ids` string[] - `declined` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - AgentActivityThreadLiveSurface: A Live Surface the agent generated; rendered as an in-chat preview (one-liner teaser) the user opens full screen. Persisted on the thread so it survives the closed async stream + reload, and so multiple surfaces in one conversation each get their own preview. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `surface_id` string, required - `title` string - `surface_kind` string - `cdn_url` string, nullable - `manifest` object, nullable - AgentActivityThreadInlineCard: An inline chat card (live-surface-styled manifest rendered in the message flow, not openable). Upserted by card_id so a build's progress card updates in place and survives reload / conversation switches. - `id` string, required - `created_at` string, date-time, required - `updated_at` string, date-time, nullable - `agent_id` string, nullable - `card_id` string, required - `kind` string - `title` string - `task_id` string, nullable - `manifest` object, required - `interaction` object, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - `context_status` ContextStatus: Per-turn snapshot of the LLM context window for the chat UI indicator. - `estimated_tokens` integer, required: Rough token count of the current message list (post-Layer-1 microcompaction). - `context_window` integer, required: Model context window size in tokens. - `percent` number, required: estimated_tokens / context_window * 100, clamped to [0, 100]. - `auto_compact_threshold` integer, required: Token level at which Layer 2 auto-compaction fires. - `emergency_threshold` integer, required: Token level at which the emergency safety net (88%) fires. - `compacting` boolean: True while a Layer 2 compaction is in flight on the current turn. - `state` 'regular' | 'agent_building' | 'agent_updating': Lifecycle phase of a gateway conversation; drives UI affordance + gateway model selection. - `usage` ConversationUsage: Cost + token usage for a conversation (or a single sub-execution). Sourced from the same monitoring rollup the api service exposes at `/v1/tasks/{task_id}/llm_usage`. Flow: chat-backend → agent-controller (in-process call) → deployment-manager (`agents_activity_proxy`) → agents service (`/{agent_id}/activity/threads/llm_usage:aggregate`) → MongoDB monitoring docs + LLM tier table Returned with the conversation as a convenience so the UI doesn't have to issue a second roundtrip per render. - `cost` number: Estimated USD cost for non-BYOK executions in this thread, rounded to 5 decimals. Excludes BYOK executions (the customer is billed by their own LLM provider for those). - `is_byok` boolean: True if any execution in the thread used BYOK credentials. - `actions` integer: Total number of agent actions (tool calls) across the thread. - `ai_model` string, nullable: Dominant LLM model id used in the thread (the model that produced the most tokens). `None` when no executions have been recorded yet. - `tokens` ConversationTokens: Aggregated token counts across every execution in the thread. `input` excludes every cache bucket (raw uncached prompt volume); `total` = input + cache_read + cache_write + output, i.e. real volume, not the billable cache-weighted figure (that lives in `usage.cost`). - `input` integer - `output` integer - `cache_read` integer - `cache_write` integer - `total` integer - `sub_executions` SubExecutionResponse[]: Triple-shape entry for every sub-execution spawned by this conversation. - `conversation_id` string, required: The sub-execution id (== its activity thread id). - `execution` AgentExecution - `background_auth_eligible` boolean - `id` string, required - `agent_id` string, required - `organization_id` string, required - `input` AgentExecutionInputOutput, required - `text` string, nullable - `files` string[], nullable - `attachments` AttachmentRef[], nullable - `url` string, required - `name` string, nullable - `mime` string, nullable - `size` integer, nullable - `kind` 'image' | 'pdf' | 'document' | 'text' | 'audio' | 'video' | 'archive' | 'unknown': Coarse attachment class, resolved from mime/magic/extension. Mirrored in xpander-sdk (models/task.py + models/generic-adjacent); keep the members identical. - `sha256` string, nullable - `expires_at` string, nullable - `source` string, nullable - `transcript` string, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - `principal` Principal: Typed caller identity: who invoked the run and through which door. - `kind` 'user' | 'slack' | 'api_key' | 'system' | 'anonymous', required - `id` string, required - `email` string, nullable - `display_name` string, nullable - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `status` 'pending' | 'executing' | 'paused' | 'error' | 'failed' | 'completed' | 'stopped' - `internal_status` string, nullable - `last_executed_node_id` string, nullable - `agent_version` string, nullable - `created_at` string, date-time, required - `started_at` string, date-time, nullable - `paused_at` string, date-time, nullable - `finished_at` string, date-time, nullable - `result` string, nullable - `parent_execution` string, nullable - `conversation_id` string, nullable - `sub_executions` string[], nullable - `finished_sub_executions` string[], nullable - `should_update_parent` boolean, nullable - `is_manually_stopped` boolean, nullable - `is_background` boolean, nullable - `payload_extension` object, nullable - `hitl_request` HumanInTheLoopRequest: Model representing human-in-the-loop approval records for tasks. Attributes: wait_node_id (str): The id of the node that triggered this HITL. - `wait_node_id` string, required - `pending_eca_request` PendingECARequest - `connector_name` string, required - `auth_url` string, required - `pending_tool_approvals` PendingToolApproval[], nullable: Tool calls held for a person's approval on this execution; each names the request id a decision route takes. - `request_id` string, required - `tool_name` string, required - `tool_label` string - `summary` string, nullable - `gate_reason` 'per_tool' | 'connector_mutating' | 'connector_read_only' | 'credential_policy' | 'gated_command' | 'elicitation' - `created_at` string, date-time, nullable - `expires_at` string, date-time, nullable - `kind` 'approval' | 'elicitation' - `message` string, nullable - `requested_schema` object, nullable - `source` string, nullable - `worker_id` string, nullable - `additional_context` string, nullable - `instructions_override` string, nullable - `expected_output` string, nullable - `engagement_instructions` string, nullable - `output_format_instructions` string, nullable - `test_run_node_id` string, nullable - `is_orchestration` boolean, nullable - `is_gateway` boolean, nullable - `conversation_kind` 'direct' | 'gateway': direct: the head row never runs a model turn, every message is one task on the agent; gateway: a router-era head. - `is_app` boolean, nullable - `is_desktop` boolean, nullable - `device_id` string, nullable - `desktop_user_id` string, nullable - `verified_user_transport` string, nullable - `sub_tasks_mode` 'sync' | 'async' | 'auto' - `output_format` 'text' | 'markdown' | 'json' | 'voice' - `voice_id` string, nullable - `output_schema` object, nullable - `events_streaming` boolean, nullable - `used_mutating_tools` boolean, nullable - `is_continuous` boolean, nullable - `mcp_servers` object[], nullable - `triggering_agent_id` string, nullable - `title` string, nullable - `think_mode` 'default' | 'harder' - `disable_attachment_injection` boolean, nullable - `deep_planning` DeepPlanning - `enabled` boolean, nullable - `enforce` boolean, nullable - `started` boolean, nullable - `question_raised` boolean, nullable - `tasks` DeepPlanningItem[], nullable - `id` string, required - `title` string, required - `description` string, nullable - `input` unknown - `output` unknown - `tool_name` string, nullable - `completed` boolean, nullable - `must_deep_plan` boolean, nullable - `short_summary` string, nullable - `execution_attempts` integer, nullable - `user_tokens` object, nullable - `user_oidc_token` string, nullable - `return_metrics` boolean, nullable - `tokens` LLMTokens - `completion_tokens` integer, nullable - `prompt_tokens` integer, nullable - `total_tokens` integer, nullable - `cache_read_tokens` integer, nullable - `cache_write_tokens` integer, nullable - `llm_model_provider` string, nullable: Snapshot of the LLM provider used for this execution (request override or agent default at run time). - `llm_model_name` string, nullable: Snapshot of the LLM model name used for this execution (request override or agent default at run time). - `llm_reasoning_effort` 'low' | 'medium' | 'high' | 'xhigh' - `execution_kind` 'turn' | 'resident': A turn ends when the CLI answers; a resident process stays Executing until the agent finishes it. - `harness_cli` 'claude-code' | 'codex' | 'opencode' | 'xpander': A CLI the harness container can run; chosen per conversation, never per agent. - `harness_cli_switches` HarnessCliSwitch[], nullable: Harness agents only: the conversation's CLI timeline, oldest first; the first entry is the CLI it started on, every later one a switch. - `cli` 'claude-code' | 'codex' | 'opencode' | 'xpander', required: A CLI the harness container can run; chosen per conversation, never per agent. - `at` string, date-time, required - `permission_mode` 'full' | 'gated' - `builtin_tools` object, nullable: Harness agents only: the resolved built-in tool sets this execution runs with, {"harness": {"enabled": bool}, "xpander": {"enabled": bool}}; inherited per half by later tasks of the conversation unless one names its own. - `tool_call_limit` integer, nullable: Max tool calls for this execution; unset leaves the agent's own ceiling in place. - `archived_at` string, date-time, nullable: When the conversation was archived; unset while it is live. - `archived_by` string, nullable: Who archived the conversation (user id), when it was. - `archived_by_agent_id` string, nullable: The agent that archived the conversation on its own, when one did; unset when a person archived it. - `deleted_at` string, date-time, nullable: When the user deleted the conversation; a deleted conversation never mirrors to history again and reads as not found. - `waiting_reason` string, nullable, required: Why a live resident process is waiting rather than working (`plan_limit`); None otherwise. - `resumes_at` string, date-time, nullable, required: When a waiting process resumes on its own (ISO), read from its booked wake; None otherwise. - `activity` AgentActivityThread - `id` string, required - `created_at` string, date-time, required - `messages` union[], required - union - AgentActivityThreadMessage - `id` string, required - `created_at` string, date-time, required - `role` 'user' | 'agent', required - `content` AgentActivityThreadMessageContent, required - … - `sub_execution_result` boolean, nullable - `is_steering` boolean, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `identity` MessageIdentity: Display identity stamped on events/messages produced under a skill. - … - `sequence` integer, nullable - `handed_back_to` HandedBackTo: The calling agent a delegated turn's final reply was returned to. - … - AgentActivityThreadToolCall - `id` string, required - `created_at` string, date-time, required - `tool_name` string, required - `operation_id` string, nullable - `agent_id` string, nullable - `payload` unknown, required - `is_error` boolean, nullable - `reasoning` ToolCallRequestReasoning - … - `result` unknown - `plan_task_id` string, nullable - `approval_request_id` string, nullable - `parent_request_id` string, nullable - `credential` ToolCallCredential: Whose credential a connector tool call resolved - ids and names only, never a value. - … - `sequence` integer, nullable - AgentActivityThreadReasoning - `id` string, required - `created_at` string, date-time, required - `type` 'think' | 'analyze', required - `title` string, required - `confidence` number, required - `thought` string, nullable - `sequence` integer, nullable - `action` string, nullable - `result` string, nullable - `analysis` string, nullable - `agent_id` string, nullable - `plan_task_id` string, nullable - AgentActivityThreadSubAgentTrigger - `id` string, required - `created_at` string, date-time, required - `agent_id` string, required - `query` string, nullable - `task_id` string, nullable - `result` string, nullable - `files` string[], nullable - `attachments` AttachmentRef[], nullable - … - `reasoning` ToolCallRequestReasoning, required - … - `plan_task_id` string, nullable - `from_agent_id` string, nullable - `from_agent_name` string, nullable - `on_behalf_of` string, nullable - `on_behalf_of_email` string, nullable - `access_reason` string, nullable - AgentActivityThreadAuth - `type` 'not_supported' | 'login_required' | 'token_issue' | 'token_ready', required - `data` union, required - … - `id` string, required - `created_at` string, date-time, required - AgentActivityThreadPlanUpdate - `enabled` boolean, nullable - `enforce` boolean, nullable - `started` boolean, nullable - `question_raised` boolean, nullable - `tasks` DeepPlanningItem[], nullable - … - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - AgentActivityThreadTaskCompactizationEvent - `id` string, required - `created_at` string, date-time, required - `type` 'retry' | 'summarization' | 'compaction_started' | 'compaction_progress' | 'manual_compaction' | 'emergency_compaction' | 'pre_retry_compaction' | 'compaction_error', required - `data` union, required - … - AgentActivityThreadGatewayCreateExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'create_execution' - `created_execution_id` string, required - `query` string - `is_async` boolean, nullable - `ack_message` string - `target_agent_id` string, nullable - `target_agent_name` string, nullable - AgentActivityThreadGatewayAskExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_execution' - `created_execution_id` string, required - `new_input` string, required - `rejected` string, nullable - AgentActivityThreadGatewayStopExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'stop_execution' - `created_execution_id` string, required - AgentActivityThreadGatewayContinueExecution - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'continue_execution' - `created_execution_id` string, required - `rejected` string, nullable - AgentActivityThreadGatewayGetExecutionsResult - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'get_executions_result' - `executions` AgentActivityThreadGatewayExecutionResultEntry[] - … - AgentActivityThreadGatewayAskUserQuestions - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_user_questions' - `questions` GatewayQuestion[] - … - `folded` boolean, nullable - `held_by_execution` string, nullable - AgentActivityThreadAskUserQuestionsAnswers: User-submitted answers to a prior ask_user_questions card. Persisted as its own activity entry (links to the question via `decision_id`) and replayed into the gateway LLM context as a user message. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `answers` GatewayAnswerItem[] - … - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadProcessUpdate: A note the agent wrote for the person while its resident process ran (`tell_user`). - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `text` string, required - `kind` 'update' | 'milestone' | 'warning' - `segment` integer - `held_by_execution` string, nullable - `sequence` integer, nullable - AgentActivityThreadGatewaySuggestTool - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'suggest_tool' - `suggestions` GatewaySuggestedTool[] - … - `allow_custom_mcp` boolean - `folded` boolean, nullable - AgentActivityThreadToolSuggestionResolved: The user's resolved choice for a prior suggest_tool card. Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the attach itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `choice` ToolSuggestionChoice, required: The tool the user picked. For a connector, either reference an existing connection (connection_id) OR carry a new-connection payload (security + meta) the backend persists — OAuth token, API key, AWS creds, etc. - … - `tool_name` string - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadGatewayInviteMember - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'invite_member' - `email` string - `role` 'member' | 'admin' | 'super_admin' | 'viewer': Role for the invited teammate (maps to the invite-members edge fn payload). - `editable` boolean - AgentActivityThreadInviteMemberResolved: The user's resolved confirmation for a prior invite_member card. Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the invite itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `email` string, required - `role` 'member' | 'admin' | 'super_admin' | 'viewer': Role for the invited teammate (maps to the invite-members edge fn payload). - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadGatewayAdminChange: A staged admin change awaiting the requester's confirmation; the id is the change id. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'admin_change' - `change_id` string - `summary` string - `before` unknown - `after` unknown - `danger` boolean - `area` string - `tool` string - `verb` string - `expires_at` string, nullable - `manifest` object, nullable - `requested_by` string - `platform_url` string - AgentActivityThreadAdminChangeResolved: The requester's answer to a staged admin change (links via `decision_id`), so the card locks on reload. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `outcome` 'applied' | 'cancelled' | 'expired' | 'refused' | 'failed', required: How a staged admin change ended. - `title` string - `detail` string - `platform_url` string - `audit_url` string - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadGatewayAskForSecret - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'ask_for_secret' - `secrets` RequiredSecret[] - … - `target_agent_id` string, nullable - `target_agent_name` string, nullable - `overwrite` boolean - AgentActivityThreadAskForSecretResolved: The user's resolution of a prior ask_for_secret card (names only, no values). Persisted as its own activity entry (links via `decision_id`) so the card locks on reload; the save itself happens in the chat-backend route. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `names` string[] - `declined` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadToolApproval: A tool call held until a person answers, rendered as an interactive card. Carries no arguments: the payload lives on the approval request, and a card the whole conversation can see must not become the place a call's inputs are published. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `reasoning` string, required - `title` string - `description` string - `action` 'tool_approval' - `request_id` string, required - `tool_label` string - `intent` string - `payload_summary` string - `statement_kind` string, nullable - `statement_target` string, nullable - `requester_name` string - `requester_user_id` string - `agent_name` string - `approver_user_ids` string[] - `approver_group_ids` string[] - `kind` string, nullable - `server` string, nullable - `message` string, nullable - `requested_schema` object, nullable - AgentActivityThreadToolApprovalResolved: The answer to a prior approval card (links via `request_id`), so it locks on reload. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `request_id` string, required - `approved` boolean - `decided_by_name` string - `decided_via` string - `note` string - `withdrawn` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadConfirmResolved: The answer to a prior confirmation card (links via `decision_id`), stamped before the resume so the card is single-use. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `approved` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadMcpRegistered: Terminal record of the MCP registration wizard (links via `decision_id`). Persisted when the enable step resolves so the wizard card locks on reload; the registry create + attach happen in the chat-backend routes. No secrets. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `decision_id` string, required - `registry_id` string - `name` string - `url` string - `enabled_agent_ids` string[] - `declined` boolean - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - … - AgentActivityThreadLiveSurface: A Live Surface the agent generated; rendered as an in-chat preview (one-liner teaser) the user opens full screen. Persisted on the thread so it survives the closed async stream + reload, and so multiple surfaces in one conversation each get their own preview. - `id` string, required - `created_at` string, date-time, required - `agent_id` string, nullable - `surface_id` string, required - `title` string - `surface_kind` string - `cdn_url` string, nullable - `manifest` object, nullable - AgentActivityThreadInlineCard: An inline chat card (live-surface-styled manifest rendered in the message flow, not openable). Upserted by card_id so a build's progress card updates in place and survives reload / conversation switches. - `id` string, required - `created_at` string, date-time, required - `updated_at` string, date-time, nullable - `agent_id` string, nullable - `card_id` string, required - `kind` string - `title` string - `task_id` string, nullable - `manifest` object, required - `interaction` object, nullable - `user` UserOutput: Represents the details of a user. Attributes: id (Optional[str]): The unique identifier of the user. Defaults to None. first_name (Optional[str]): The first name of the user. Defaults to None. last_name (Optional[str]): The last name of the user. Defaults to None. email (str): The email address of the user. This field is required. additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service. role (Optional[str]): The user's role in the organization. Defaults to "member". is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False. timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None. - `id` string, nullable - `first_name` string, nullable - `last_name` string, nullable - `email` string, required - `additional_attributes` object, nullable - `role` string, nullable - `is_super_admin` boolean, nullable - `timezone` string, nullable - `display_name` string, required - `context_status` ContextStatus: Per-turn snapshot of the LLM context window for the chat UI indicator. - `estimated_tokens` integer, required: Rough token count of the current message list (post-Layer-1 microcompaction). - `context_window` integer, required: Model context window size in tokens. - `percent` number, required: estimated_tokens / context_window * 100, clamped to [0, 100]. - `auto_compact_threshold` integer, required: Token level at which Layer 2 auto-compaction fires. - `emergency_threshold` integer, required: Token level at which the emergency safety net (88%) fires. - `compacting` boolean: True while a Layer 2 compaction is in flight on the current turn. - `state` 'regular' | 'agent_building' | 'agent_updating': Lifecycle phase of a gateway conversation; drives UI affordance + gateway model selection. - `usage` ConversationUsage: Cost + token usage for a conversation (or a single sub-execution). Sourced from the same monitoring rollup the api service exposes at `/v1/tasks/{task_id}/llm_usage`. Flow: chat-backend → agent-controller (in-process call) → deployment-manager (`agents_activity_proxy`) → agents service (`/{agent_id}/activity/threads/llm_usage:aggregate`) → MongoDB monitoring docs + LLM tier table Returned with the conversation as a convenience so the UI doesn't have to issue a second roundtrip per render. - `cost` number: Estimated USD cost for non-BYOK executions in this thread, rounded to 5 decimals. Excludes BYOK executions (the customer is billed by their own LLM provider for those). - `is_byok` boolean: True if any execution in the thread used BYOK credentials. - `actions` integer: Total number of agent actions (tool calls) across the thread. - `ai_model` string, nullable: Dominant LLM model id used in the thread (the model that produced the most tokens). `None` when no executions have been recorded yet. - `tokens` ConversationTokens: Aggregated token counts across every execution in the thread. `input` excludes every cache bucket (raw uncached prompt volume); `total` = input + cache_read + cache_write + output, i.e. real volume, not the billable cache-weighted figure (that lives in `usage.cost`). - `input` integer - `output` integer - `cache_read` integer - `cache_write` integer - `total` integer - `feedbacks` MessageFeedbackItem[]: Per-message feedback rows recorded against this sub-execution. - `id` string, nullable - `agent_id` string, nullable - `conversation_id` string, nullable: Task/thread id this feedback belongs to. - `message_id` string, required: The feedbacked activity message id. - `user_id` string, nullable - `is_positive` boolean, required: True for thumbs-up, false for thumbs-down. - `comment` string, nullable - `created_at` string, nullable - `updated_at` string, nullable - `feedbacks` MessageFeedbackItem[]: Per-message feedback rows recorded against the parent execution. - `id` string, nullable - `agent_id` string, nullable - `conversation_id` string, nullable: Task/thread id this feedback belongs to. - `message_id` string, required: The feedbacked activity message id. - `user_id` string, nullable - `is_positive` boolean, required: True for thumbs-up, false for thumbs-down. - `comment` string, nullable - `created_at` string, nullable - `updated_at` string, nullable ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/xpander/apis/xpander-ai-api-service.md) - [All operations](https://skmtc.dev/xpander/apis/xpander-ai-api-service/llms.txt) - [OpenAPI document](https://skmtc.dev/xpander/apis/xpander-ai-api-service/revisions/4389ec0875d0?raw)