> ## Documentation Index > Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Companion activation history > Paginate the authorized initialization snapshot before submitting one combined agent input ```text theme={null} GET /api/v1/identities/{agent_handle}/companion/activations/{activation_id}/messages ``` Read a finite, chronological initialization snapshot for an activation UUID obtained from [conversation state](/docs/api/identities/companion-conversations) or a verified [received webhook](/docs/webhooks#companion-conversation-events). This endpoint supplies retained authorized history plus exactly one sponsor trigger. It is not a live-message feed. The sponsor is the actual author of the entry marked `is_trigger: true`. Their qualifying authenticated group message must meet the [exact bidirectional-allow requirements](/docs/capabilities/companion-mode#who-can-introduce-the-agent). Other eligible senders do not replace that author or restart the active snapshot. Current authorization still depends on the original sponsor's rules and membership. Admin-scoped API keys and human sessions may request an activation belonging to an identity in their organization. Claimed identity-scoped keys may request only their own identity. All callers still need a currently available activation. Unclaimed keys are not supported. Authorization is checked on every page; possession of an activation ID or cursor does not grant access. ## Query parameters | Parameter | Type | Default | Meaning | | :-------- | :------ | :------ | :---------------------------------------------------------------------------------- | | `limit` | integer | `100` | Entries per page, `1` through `200`. | | `cursor` | string | None | Opaque `next_cursor` from this activation's previous page, at most 1024 characters. | ## Response | Field | Type | Meaning | | :----------------- | :-------------- | :------------------------------------------------------------------------------------------------ | | `scope_id` | UUID | Conversation-and-cohort scope. | | `activation_id` | UUID | Initialization activation. | | `conversation_id` | UUID | Canonical channel conversation. | | `channel` | string | `mail`, `phone`, or `imessage`. | | `items` | array | Ordered source entries for this page. | | `history_complete` | boolean | `true` only at the end of the authorized snapshot. | | `next_cursor` | string or null | Continue while non-null. The final page has `null`. | | `reply_context` | object | Canonical conversation and email reply audience where applicable. | | `notices` | array, optional | Advisory notices; `history_unavailable` can report earlier messages that are no longer available. | ### Source entry | Field | Type | Meaning | | :-------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | UUID | Source message ID for deduplication. | | `author` | string | Message author, not necessarily the sponsor. | | `sender_access` | `"direct"` or `"sponsored"`, optional | Receipt-time admission of this inbound message; absent when unknown or inapplicable, including outbound entries. Not sender trust or command permission. | | `occurred_at` | timestamp | Source message time. | | `text` | string | Message content; can be empty for an attachment-only message. | | `historical` | boolean | Earlier context rather than a new live instruction. | | `is_trigger` | boolean | Whether this is the sponsor message that activated the snapshot. Exactly one across the full snapshot. | | `attachments` | object\[] | Authorized attachment metadata/references, not inline attachment bodies. | See [per-message sender access](/docs/webhooks#per-message-sender-access) for semantics and legacy/system exceptions. Inline history and every paginated page use the same field. Preserve it through full snapshot loading; never default missing evidence to `direct`. ### Reply context | Field | Type | Meaning | | :-------------------- | :---------------- | :-------------------------------------------------------------------------------------------------------------- | | `channel` | string | Same channel as the snapshot. | | `conversation_id` | UUID | Use this for an existing phone/iMessage conversation reply. | | `reply_to_message_id` | UUID or null | Stored email parent message ID for [reply-all](/docs/api/mail/messages#reply-to-everyone), not its RFC `Message-ID`. | | `to` / `cc` | string\[] or null | Exact permitted email audience. Not a grant for a raw recipient-only send. | Phone/iMessage reply contexts can omit or return null for email-specific fields. Keep the context associated with the current activation and turn; do not infer a private reply target from the last author. ## Read a page These SDK examples assume an authenticated `client` and an activation ID from a verified event or state response. They fetch **one page**, not a complete initialization. ```python Python theme={null} page = client.companion.activation_messages("xyz", activation_id, limit=100) print(page.history_complete, page.next_cursor) ``` ```typescript TypeScript theme={null} const page = await client.companion.activationMessages("xyz", activationId, { limit: 100 }); console.log(page.historyComplete, page.nextCursor); ``` ```rust Rust theme={null} use inkbox::companion::CompanionActivationOptions; use inkbox::Inkbox; fn page(client: &Inkbox, activation_id: &str) -> inkbox::Result<()> { let page = client.companion().activation_messages( "xyz", activation_id, &CompanionActivationOptions::default(), )?; println!("{} {:?}", page.history_complete, page.next_cursor); Ok(()) } ``` ```bash CLI theme={null} inkbox identity companion history xyz "$ACTIVATION_ID" --limit 100 --json inkbox identity companion history xyz "$ACTIVATION_ID" --limit 100 --cursor "$NEXT_CURSOR" --json ``` For manual pagination, pass the returned `next_cursor` as Python `cursor`, TypeScript `cursor`, or Rust `CompanionActivationOptions.cursor` on the next request. Continue until `history_complete` is true and the cursor is null. Retain the entries from every page before constructing context. For an agent receiver, prefer the [complete initialization helpers](/docs/capabilities/companion-mode#load-complete-initialization), which retain entries, validate consistent scope and cursor progress, deduplicate sources, enforce byte/page bounds, and revalidate before returning. CLI JSON uses `historyComplete`, `nextCursor`, and `replyContext`; raw API JSON uses snake\_case. ## Initialization rules * Finish every page before submitting one combined agent input. Never wake the host once per page, source message, or attachment. * Preserve authors, times, per-message sender access, historical markers, attachment references, notices, and the trigger exactly once. Historical commands are context, not new control messages. * Buffer live events during initialization and persist a durable activation/host-turn checkpoint before releasing them. Recover missing initialization even when the first event observed is `live`. * The snapshot contains only retained authorized messages delivered to this identity in this scope. Completion does not promise history from before the agent joined or messages that are no longer available. * New arrivals do not extend this snapshot. Read them through received events or ordinary channel history, deduplicating against initialized source IDs. * Recheck current authorization before a delayed submission. If access ends, discard pending Companion-only context rather than submitting a partial initialization. An API page supports up to 32 MiB of message content. A `413` requires a smaller `limit`; an individually oversized message still fails. SDK initialization has a separate default 8 MiB total bound and does not automatically reduce the page size after `413`. Use the page API for a custom bounded, lossless context-loading path. ## Errors | Status | Meaning | | :----- | :------------------------------------------------------------------------------------------------------------------------------- | | `403` | The caller is not authorized for the requested identity. | | `404` | The activation is unavailable to this identity/caller. | | `409` | Initialization is not currently available, a required message is unavailable, or history changed. Refresh state before retrying. | | `413` | A page or individual message is too large. No truncated successful snapshot is returned. | | `422` | Invalid activation ID, limit, or cursor, including a cursor from another activation. | | `503` | Message content or current group membership is temporarily unavailable. Retry later without submitting partial context. | See [webhook recovery](/docs/webhooks#companion-conversation-events) and [response notices](/docs/get-started/response-notices). Notices never replace error handling or grant permission.