> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aixy-gateway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Activity

> Explore model and MCP execution timelines, conversation consumption, and recorded cost evidence.

**Activity** explains what happened to a model request: the requested and effective models,
provider, routing attempts, timing, usage, policy decisions, and available cost evidence.
It is the place to start when a client reports a failed or unexpectedly expensive request.

## Find a request

1. Copy the `x-request-id` response header from your application, or use the Activity link on a
   Playground error.
2. Open **Activity** in the dashboard and search for that request ID.
3. For a broader investigation, choose the project, time range, provider, model, user, team, or
   status, then select **Apply filters**.
4. Open a row to inspect its detail and attempt history.

The default search covers the last 24 hours. Presets and custom ranges use the displayed local
timezone; applying the filters saves fixed times in the URL so a shared link keeps the same window.
Request-ID searches use the available retention window. Your project and user permissions still
apply when opening a shared link.

## Explore a conversation

Open **Activity → Sessions** to see the calls belonging to a conversation, their token usage,
attributed cost, errors, and first/last activity. Open a session to inspect its consumption and
chronological model requests and MCP actions, then open an individual model request for routing, timing, policy, and cost evidence.

Send an opaque `X-Aixy-Session-ID` with every model call in the conversation. Generate a new ID
when a new conversation starts. For example, with the OpenAI Python client:

```python theme={null}
import uuid

session_id = str(uuid.uuid4())  # Keep this value for all turns in this conversation.
response = client.chat.completions.create(
    model="aixy/support",
    messages=conversation_messages,
    extra_headers={"X-Aixy-Session-ID": session_id},
)
```

Use 1–128 ASCII letters, digits, dots, underscores, colons or hyphens without personal data or
secrets. Invalid identifiers are ignored. The header is recorded only as diagnostic metadata;
it is not forwarded and does not change permissions or model routing. The routing-affinity header
`X-Aixy-Session` remains separate and is not recorded.

**Playground** conversations are grouped automatically, including multiple model rounds and approved MCP actions. **New
conversation** starts a new session. Aixy also recognizes allowlisted session identifiers supplied
by Codex and Claude Code, explicit `metadata.session_id`, `client_metadata.thread_id` or
`client_metadata.session_id`, and `x-litellm-session-id`. Client versions and intermediaries can
change which metadata reaches the gateway; verify that your request appears in Sessions.

A session is scoped to the authenticated organization, project, user and API key. The same ID from
another scope produces a separate session. No prompts or responses need to be captured to group
calls. Older calls without an identifier stay in **Requests**.

Totals cover all matching retained calls in the selected period, including fallback attempts;
they are calculated before pagination. Start with the default 24 hours or choose a wider retained
period. Searching a session ID without a selected period searches retained history up to 90 days.
Your project and user permissions still apply. The observed span includes idle time between calls.

A cost total adds only recorded attributed amounts. Coverage shows how many calls have cost
information; missing or partial cost is marked incomplete. A dash means no amount is available,
not free usage. Cost statuses distinguish estimates from provider-reported or reconciled evidence.
Token coverage likewise identifies calls with missing totals. Cache and reasoning tokens may be
subsets of other token classes and are not added again to total tokens. Asynchronous telemetry and
retention can limit what is available.

MCP clients send the same `X-Aixy-Session-ID` on tool calls and `X-Aixy-API-Key-ID` naming the
inference key used for the model rounds. This is the key's non-secret ID, not its bearer secret.
Aixy checks that the key is active, belongs to the MCP token's user and organization, and matches
the authorized project. Omitting the key ID produces a separate tool-only session; Aixy does not
guess which key the client used. `MCP-Session-Id` remains the independent tool-discovery context.

**Requests** includes unlinked historical model and MCP calls. A session timeline is ordered oldest
first and preserves individual model details. Tool rows show server, action, status, duration and
request ID. MCP call records exclude tool arguments, results and credentials. Opt-in model captures can
include tool history already sent in model prompts. Running or unknown
actions may have completed externally; check their outcome before submitting another action.

MCP counts are separate from model consumption. Tokens, cost and their coverage count model calls;
external tool costs are not recorded. MCP call metadata follows its existing retention and bounded
history, independently of model usage. If a data source is unavailable, Activity names it and marks
the visible timeline and totals incomplete. Late telemetry, retention and deletion can change the
available rows while paging. For a very dense history, narrow the selected period.

## Interpret the detail

| Evidence | What it helps explain |
| - | - |
| Identity and client | Project, key owner, team attribution, and recorded calling application |
| Requested and effective model | A direct call or the concrete target selected behind a routing alias |
| Attempts | Why a target was chosen, its outcome, provider request ID when recorded, and fallback behavior |
| Timing | Total duration, provider time, gateway overhead, time to first byte, and streaming duration |
| Usage and cost | Token classes, amount, source, and reasons for partial or missing attribution |
| Decisions | Recorded budget, guardrail, model-routing, and cache evidence |

Provider error explanations distinguish authentication, permissions, model access, parameters,
context limits, quota, rate limits, overload, and availability when the provider supplies recognized
evidence. Earlier records may have only an HTTP status; inspect what was actually recorded.
A failed upstream attempt may still have cost or an uncertain outcome. A budget reservation alone
does not establish provider billing.

Activity is asynchronous diagnostic telemetry. A record can be delayed or missing if telemetry
export fails. Historical fields without evidence stay unknown rather than being reconstructed.

## Configure content capture

Prompts and responses are not captured by default. An authorized administrator can select
**Configure capture** in Activity, choose the organization or project under **Policy scope**, and:

1. Enable prompts, responses, or both.
2. Choose retention of 1, 3, 7, 30, or 90 days.
3. Save the policy and make a new test request.
4. Open the resulting request and explicitly retrieve its content with a role that permits it.

A project capture setting overrides the organization default, including an explicitly disabled
setting. Each captured side has a 150,000-byte bound. Oversized content is marked as too long and
is not partially stored. Capture status explains when content was not collected or is no longer
available.

Captured content is encrypted and stored separately from usage metadata. It is not included in
customer telemetry exports. Only authorized content readers can retrieve it; capture configuration
and content access require additional permissions. Retention expiry removes live captures;
backups follow their own retention policy.

## Correlate application requests

Store the gateway request ID with your application's diagnostic logs. You can also declare a
product name and optional version using `X-Aixy-Client`, for example `Support Service/1.2.3`.
Use product identifiers without personal data or secrets. Client labels help investigation but do
not authenticate a user or change permissions.

For configuration changes, use the [Audit log](/observe/audit-log). For external tool execution,
use the common **Activity** timeline as described in [Agent tools](/agent-tools/overview).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.