Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add observability narrative for logs + usage APIs

shams haroonbe30c1c2be63
diff --git a/docs/content/changelog/04-17-26.mdx b/docs/content/changelog/04-17-26.mdx
new file mode 100644
index 000000000..dd92fb0c1
--- /dev/null
+++ b/docs/content/changelog/04-17-26.mdx
@@ -0,0 +1,29 @@
+---
+title: "Observability APIs: tool execution logs and usage metering"
+description: "Query individual tool execution logs and aggregated usage counts for your org or project via v3.1 REST endpoints."
+date: "2026-04-17"
+---
+
+Two new v3.1 observability API surfaces are live.
+
+## Tool execution logs
+
+Search, filter, and paginate individual tool execution events. Use this for debugging failures, inspecting request/response payloads, and tracing user activity.
+
+- `POST /api/v3.1/logs/tool_execution` — list with filters, time range, and cursor pagination.
+- `GET /api/v3.1/logs/tool_execution/{id}` — full detail including request payload, response body, timings, and source metadata.
+
+Authentication: project API key (`x-api-key`) or session cookie.
+
+See the [tool execution logs guide](/docs/observability/logs).
+
+## Usage metering
+
+Aggregated counts of tool calls and sessions, sourced from ClickHouse. Summary endpoints return totals; breakdown endpoints group results by tool, toolkit, user, session, or project.
+
+- `POST /api/v3.1/org/usage/summary` and `POST /api/v3.1/org/usage/{entity_type}` — org scope (`x-org-api-key` or org JWT).
+- `POST /api/v3.1/project/usage/summary` and `POST /api/v3.1/project/usage/{entity_type}` — project scope (`x-api-key` or cookie).
+
+Entity types: `tool_calls`, `sessions`. Time ranges are epoch milliseconds; max range 366 days.
+
+See the [usage metering guide](/docs/observability/usage).
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index cfd52473c..7989b744d 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -29,6 +29,7 @@
"sessions-vs-direct-execution",
"---Features---",
"projects",
+ "observability",
"single-toolkit-mcp",
"---Direct Tool Execution Guides---",
"tools-direct",
diff --git a/docs/content/docs/observability/index.mdx b/docs/content/docs/observability/index.mdx
new file mode 100644
index 000000000..0347e8863
--- /dev/null
+++ b/docs/content/docs/observability/index.mdx
@@ -0,0 +1,36 @@
+---
+title: Observability
+description: Inspect tool execution activity and usage for your org or project.
+keywords: ['observability', 'logs', 'usage', 'metering', 'metrics']
+---
+
+Composio exposes two v3.1 REST APIs for inspecting activity in your org or project: a **Logs API** for individual tool execution events and a **Usage API** for aggregated counts. Use this page to figure out which one to call.
+
+## Which API should I use?
+
+| I want to... | Use |
+|---|---|
+| Debug a specific tool execution (payloads, errors, timing) | [Tool execution logs](/docs/observability/logs) |
+| See how many tool calls or sessions happened in a window | [Usage summary](/docs/observability/usage#summary) |
+| Break usage down by tool, toolkit, user, or session | [Usage breakdown](/docs/observability/usage#breakdown) |
+
+Logs record **individual events** and are primarily for debugging. Usage queries return **aggregated counts** from ClickHouse and are primarily for dashboards, billing integrations, and customer-facing analytics.
+
+## Authentication at a glance
+
+Each endpoint family takes a specific credential. Use the right one for the scope you need.
+
+| Endpoints | Header | Scope |
+|---|---|---|
+| `POST /api/v3.1/org/usage/summary`<br/>`POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
+| `POST /api/v3.1/project/usage/summary`<br/>`POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or session cookie)* | Single project |
+| `POST /api/v3.1/logs/tool_execution`<br/>`GET /api/v3.1/logs/tool_execution/{id}` | `x-api-key` *(or session cookie)* | Single project |
+
+The org-level usage endpoints accept a `project_id` filter so you can slice by project without rotating keys.
+
+## Reference
+
+For full request/response schemas, see the auto-generated reference:
+
+- [Organization API reference](/reference/api-reference/organization) — org-level usage endpoints
+- [Projects API reference](/reference/api-reference/projects) — project-level usage endpoints and project-scoped APIs
diff --git a/docs/content/docs/observability/logs.mdx b/docs/content/docs/observability/logs.mdx
new file mode 100644
index 000000000..04f5cdc9c
--- /dev/null
+++ b/docs/content/docs/observability/logs.mdx
@@ -0,0 +1,149 @@
+---
+title: Tool execution logs
+description: Search, filter, and inspect individual tool execution logs for debugging and forensics.
+keywords: ['logs', 'tool execution', 'debugging', 'observability']
+---
+
+The Logs API returns **individual tool execution events** — one record per tool call. Use it to debug failures, inspect request/response payloads, and trace specific user activity. For aggregated counts (how many tool calls happened), use the [Usage API](/docs/observability/usage) instead.
+
+All endpoints in this section require a **project API key** (`x-api-key`) or a valid session cookie.
+
+## List logs
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "limit": 20,
+ "time_range": {
+ "from": 1744848000000,
+ "to": 1744934400000
+ },
+ "filters": [
+ { "field": "toolkit_slug", "operator": "==", "value": "gmail" },
+ { "field": "status", "operator": "==", "value": "failed" }
+ ]
+ }'
+```
+
+The response contains a page of log entries and a `next_cursor`:
+
+```json
+{
+ "logs": [
+ {
+ "id": "log_-jRTWClpBoVo",
+ "timestamp": "2026-04-17T10:25:00.000Z",
+ "type": "tool.execution",
+ "status": "failed",
+ "level": "error",
+ "message": "GMAIL_SEND_EMAIL failed: invalid recipient",
+ "metadata": { /* tool, toolkit, user_id, connected_account_id, ... */ },
+ "metrics": { "duration_ms": 202 },
+ "parent": null
+ }
+ ],
+ "next_cursor": "eyJwYWdlIjoyfQ=="
+}
+```
+
+Pass `next_cursor` back as `cursor` on the next request to paginate. When `next_cursor` is `null`, you've reached the end.
+
+### Filter fields
+
+Pass one or more filters in the `filters` array. Filters are **AND**-combined.
+
+| Field | What it matches |
+|---|---|
+| `tool_slug` | The specific tool that was called (e.g. `GMAIL_SEND_EMAIL`) |
+| `toolkit_slug` | The toolkit (e.g. `gmail`, `slack`, `github`) |
+| `connected_account_id` | The connected account used for the call |
+| `auth_config_id` | The auth config (integration) behind the connected account |
+| `status` | `success` or `failed` |
+| `user_id` | Entity that initiated the call |
+| `session_id` | Tool router session, if routed through a session |
+| `sandbox_id` | Sandbox the call ran in, if applicable |
+| `request_id` | Request ID (useful for correlating with your own logs) |
+| `log_id` | Exact log ID (equivalent to the detail endpoint) |
+
+### Operators
+
+| Operator | Meaning |
+|---|---|
+| `==` | Exact match |
+| `!=` | Not equal |
+| `contains` | Substring match |
+| `not_contains` | Substring does not match |
+
+### Parameters
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `limit` | number | `20` | Max 100 |
+| `cursor` | string \| null | `null` | Opaque pagination token from previous response |
+| `filters` | array | `[]` | AND-combined |
+| `time_range.from` | number | — | Epoch milliseconds |
+| `time_range.to` | number | — | Epoch milliseconds |
+
+## Get a single log
+
+Fetch one log by ID to get the **full** payload, including request/response bodies, timing breakdowns, and source metadata:
+
+```bash
+curl https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
+ -H "x-api-key: YOUR_PROJECT_API_KEY"
+```
+
+The detail response includes everything from the list shape plus:
+
+- `timings` — `start_time` and `end_time` in epoch ms
+- `context` — `session_id`, `trace_id`, `request_id`
+- `source` — `host` (e.g. `mcp`, `sdk`, `api`), `framework`, `language`
+- `data` — the full request payload and response body
+
+This is the endpoint to call when you need to reconstruct *exactly* what happened — e.g. when debugging a 500 from a user report.
+
+## Recipes
+
+### Find failed Gmail tool calls in the last hour
+
+```bash
+NOW=$(date +%s)000
+HOUR_AGO=$(( $(date +%s) - 3600 ))000
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"time_range\": { \"from\": ${HOUR_AGO}, \"to\": ${NOW} },
+ \"filters\": [
+ { \"field\": \"toolkit_slug\", \"operator\": \"==\", \"value\": \"gmail\" },
+ { \"field\": \"status\", \"operator\": \"==\", \"value\": \"failed\" }
+ ]
+ }"
+```
+
+### Get failures for a specific user
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "filters": [
+ { "field": "user_id", "operator": "==", "value": "user_abc123" },
+ { "field": "status", "operator": "==", "value": "failed" }
+ ]
+ }'
+```
+
+### Fetch a single log's full request/response
+
+```bash
+curl https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
+ -H "x-api-key: YOUR_PROJECT_API_KEY"
+```
+
+## Reference
+
+See the [Projects API reference](/reference/api-reference/projects) for the generated schema.
diff --git a/docs/content/docs/observability/meta.json b/docs/content/docs/observability/meta.json
new file mode 100644
index 000000000..8bdec011e
--- /dev/null
+++ b/docs/content/docs/observability/meta.json
@@ -0,0 +1,4 @@
+{
+ "title": "Observability",
+ "pages": ["index", "logs", "usage"]
+}
diff --git a/docs/content/docs/observability/usage.mdx b/docs/content/docs/observability/usage.mdx
new file mode 100644
index 000000000..b5ce6233c
--- /dev/null
+++ b/docs/content/docs/observability/usage.mdx
@@ -0,0 +1,203 @@
+---
+title: Usage metering
+description: Query aggregated tool call and session counts for your org or project, with rich filtering and breakdown options.
+keywords: ['usage', 'metering', 'analytics', 'billing', 'observability']
+---
+
+The Usage API returns **aggregated counts** of tool calls and sessions, sourced from ClickHouse. Use it to power billing dashboards, customer-facing analytics, or internal utilization reports. For individual events, use the [Logs API](/docs/observability/logs).
+
+There are two query shapes:
+
+- **Summary** — totals across one or more entity types in a time window.
+- **Breakdown** — one entity type, grouped by a dimension (tool, user, session, etc.).
+
+Each shape comes in an org-scoped and a project-scoped flavor.
+
+## Authentication
+
+| Endpoint | Header | Scope |
+|---|---|---|
+| `POST /api/v3.1/org/usage/summary` | `x-org-api-key` *(or org JWT)* | All projects in your org |
+| `POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
+| `POST /api/v3.1/project/usage/summary` | `x-api-key` *(or cookie)* | Single project |
+| `POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or cookie)* | Single project |
+
+The org endpoints accept a `project_id` filter so you can slice by project without rotating keys.
+
+## Entity types
+
+| Entity type | What it counts |
+|---|---|
+| `tool_calls` | Every tool execution (successful or failed) |
+| `sessions` | Tool router sessions created |
+
+## Summary
+
+Totals across entity types for a time window.
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/summary \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "from": 1744848000000,
+ "to": 1744934400000,
+ "entity_types": ["tool_calls", "sessions"]
+ }'
+```
+
+Response:
+
+```json
+{
+ "entities": {
+ "tool_calls": { "unit": "count", "total_quantity": "142", "event_count": 142 },
+ "sessions": { "unit": "count", "total_quantity": "8", "event_count": 8 }
+ }
+}
+```
+
+### Summary parameters
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `from` | number | 30 days ago | Epoch milliseconds |
+| `to` | number | now | Epoch milliseconds |
+| `entity_types` | string[] | all | Subset of `tool_calls`, `sessions` |
+| `filters.user_id` | string \| string[] | — | Filter events by initiating user |
+| `filters.session_id` | string \| string[] | — | Filter events by tool router session |
+| `filters.project_id` | string \| string[] | — | Only meaningful on org endpoints; ignored on project endpoints |
+
+## Breakdown
+
+One entity type, grouped by a dimension. Useful for answering "top N" questions.
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "from": 1744848000000,
+ "to": 1744934400000,
+ "group_by": "toolkit_slug",
+ "order_by": "total_quantity",
+ "order_direction": "desc",
+ "limit": 10
+ }'
+```
+
+Response:
+
+```json
+{
+ "entity_type": "tool_calls",
+ "unit": "count",
+ "total_quantity": "142",
+ "event_count": 142,
+ "groups": [
+ { "key": "github", "total_quantity": "80", "event_count": 80 },
+ { "key": "slack", "total_quantity": "62", "event_count": 62 }
+ ]
+}
+```
+
+### Breakdown `group_by` options
+
+| Entity | Org scope | Project scope | Default |
+|---|---|---|---|
+| `tool_calls` | `tool_slug`, `toolkit_slug`, `connected_account_id`, `user_id`, `session_id`, `project_id` | same minus `project_id` | `tool_slug` |
+| `sessions` | `user_id`, `project_id` | `user_id` | `user_id` |
+
+### Breakdown parameters
+
+| Field | Type | Default | Notes |
+|---|---|---|---|
+| `from` | number | 30 days ago | Epoch ms |
+| `to` | number | now | Epoch ms |
+| `group_by` | string | see table | Dimension to group by |
+| `order_by` | string | `total_quantity` | One of `key`, `total_quantity`, `event_count` |
+| `order_direction` | `"asc"` \| `"desc"` | `"desc"` | |
+| `limit` | number | 50 | Max groups returned |
+| `filters` | object | — | See Filters below |
+
+## Filters
+
+Filters live in a `filters` object on the request body. Each filter value can be a **single string** or an **array of strings**:
+
+- Within a single field, values are OR-combined (`user_id: ["a", "b"]` matches events for user *a or b*).
+- Across fields, filters are AND-combined.
+
+```json
+{
+ "filters": {
+ "user_id": ["user_123", "user_456"],
+ "session_id": "sess_abc"
+ }
+}
+```
+
+The `project_id` filter is only meaningful on the org-scoped endpoints. Project endpoints accept the field but ignore it (your key already pins the scope to a single project).
+
+## Time ranges
+
+- `from` and `to` are **epoch milliseconds**.
+- `from` defaults to 30 days before `to`.
+- `to` defaults to the current time.
+- Maximum range: **366 days**. Longer ranges return a 400.
+
+## Recipes
+
+### Top 10 tools my org called last week
+
+```bash
+WEEK_AGO=$(( $(date +%s) - 604800 ))000
+NOW=$(date +%s)000
+curl -X POST https://backend.composio.dev/api/v3.1/org/usage/tool_calls \
+ -H "x-org-api-key: YOUR_ORG_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"from\": ${WEEK_AGO},
+ \"to\": ${NOW},
+ \"group_by\": \"tool_slug\",
+ \"limit\": 10
+ }"
+```
+
+### Tool call count per user for my project this month
+
+```bash
+MONTH_AGO=$(( $(date +%s) - 2592000 ))000
+NOW=$(date +%s)000
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d "{
+ \"from\": ${MONTH_AGO},
+ \"to\": ${NOW},
+ \"group_by\": \"user_id\",
+ \"limit\": 50
+ }"
+```
+
+### Which toolkits is a specific user using?
+
+```bash
+curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
+ -H "x-api-key: YOUR_PROJECT_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "group_by": "toolkit_slug",
+ "filters": { "user_id": "user_abc123" }
+ }'
+```
+
+## Self-hosted deployments
+
+If your Composio instance is self-hosted **without ClickHouse enabled**, the usage endpoints return `500`. The Logs API does not depend on ClickHouse and remains available.
+
+## Reference
+
+See the auto-generated reference for full schemas:
+
+- [Organization API reference](/reference/api-reference/organization) — org-level usage endpoints
+- [Projects API reference](/reference/api-reference/projects) — project-level usage endpoints