Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxnew file mode 100644index 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.jsonindex 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.mdxnew file mode 100644index 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 APIsdiff --git a/docs/content/docs/observability/logs.mdx b/docs/content/docs/observability/logs.mdxnew file mode 100644index 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.jsonnew file mode 100644index 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.mdxnew file mode 100644index 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