Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | --- |
| 2 | title: Logs |
| 3 | description: "Logging and monitoring" |
| 4 | --- |
| 5 | |
| 6 | {/* Auto-generated from OpenAPI spec. Edit the overview at api-overviews/logs.mdx, not this file. */} |
| 7 | |
| 8 | 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](/reference/api-reference/organization) instead. |
| 9 | |
| 10 | All endpoints in this section require a **project API key** (`x-api-key`) or a valid session cookie. |
| 11 | |
| 12 | ## List logs |
| 13 | |
| 14 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 15 | <Tab value="Python"> |
| 16 | ```python |
| 17 | from composio import Composio |
| 18 | |
| 19 | composio = Composio() |
| 20 | |
| 21 | page = composio.logs.search( |
| 22 | limit=20, |
| 23 | time_range={"from": 1744848000000, "to": 1744934400000}, |
| 24 | filters=[ |
| 25 | {"field": "toolkit_slug", "operator": "==", "value": "gmail"}, |
| 26 | {"field": "status", "operator": "==", "value": "failed"}, |
| 27 | ], |
| 28 | ) |
| 29 | print(page.logs, page.next_cursor) |
| 30 | ``` |
| 31 | </Tab> |
| 32 | <Tab value="TypeScript"> |
| 33 | ```typescript |
| 34 | import { Composio } from '@composio/core'; |
| 35 | |
| 36 | const composio = new Composio(); |
| 37 | |
| 38 | const { logs, nextCursor } = await composio.logs.search({ |
| 39 | limit: 20, |
| 40 | timeRange: { from: 1744848000000, to: 1744934400000 }, |
| 41 | filters: [ |
| 42 | { field: 'toolkit_slug', operator: '==', value: 'gmail' }, |
| 43 | { field: 'status', operator: '==', value: 'failed' }, |
| 44 | ], |
| 45 | }); |
| 46 | console.log(logs, nextCursor); |
| 47 | ``` |
| 48 | </Tab> |
| 49 | <Tab value="API"> |
| 50 | ```bash |
| 51 | curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \ |
| 52 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 53 | -H "Content-Type: application/json" \ |
| 54 | -d '{ |
| 55 | "limit": 20, |
| 56 | "time_range": { |
| 57 | "from": 1744848000000, |
| 58 | "to": 1744934400000 |
| 59 | }, |
| 60 | "filters": [ |
| 61 | { "field": "toolkit_slug", "operator": "==", "value": "gmail" }, |
| 62 | { "field": "status", "operator": "==", "value": "failed" } |
| 63 | ] |
| 64 | }' |
| 65 | ``` |
| 66 | </Tab> |
| 67 | </Tabs> |
| 68 | |
| 69 | The response contains a page of log entries and a `next_cursor`: |
| 70 | |
| 71 | ```json |
| 72 | { |
| 73 | "logs": [ |
| 74 | { |
| 75 | "id": "log_-jRTWClpBoVo", |
| 76 | "timestamp": "2026-04-17T10:25:00.000Z", |
| 77 | "type": "tool.execution", |
| 78 | "status": "failed", |
| 79 | "level": "error", |
| 80 | "message": "GMAIL_SEND_EMAIL failed: invalid recipient", |
| 81 | "metadata": { /* tool, toolkit, user_id, connected_account_id, ... */ }, |
| 82 | "metrics": { "duration_ms": 202 }, |
| 83 | "parent": null |
| 84 | } |
| 85 | ], |
| 86 | "next_cursor": "eyJwYWdlIjoyfQ==" |
| 87 | } |
| 88 | ``` |
| 89 | |
| 90 | Pass `next_cursor` back as `cursor` on the next request to paginate. When `next_cursor` is `null`, you've reached the end. |
| 91 | |
| 92 | ### Filter fields |
| 93 | |
| 94 | Pass one or more filters in the `filters` array. Filters are **AND**-combined. |
| 95 | |
| 96 | | Field | What it matches | |
| 97 | |---|---| |
| 98 | | `tool_slug` | The specific tool that was called (e.g. `GMAIL_SEND_EMAIL`) | |
| 99 | | `toolkit_slug` | The toolkit (e.g. `gmail`, `slack`, `github`) | |
| 100 | | `connected_account_id` | The connected account used for the call | |
| 101 | | `auth_config_id` | The auth config (integration) behind the connected account | |
| 102 | | `status` | `success` or `failed` | |
| 103 | | `user_id` | Entity that initiated the call | |
| 104 | | `session_id` | Tool router session, if routed through a session | |
| 105 | | `sandbox_id` | Sandbox the call ran in, if applicable | |
| 106 | | `request_id` | Request ID (useful for correlating with your own logs) | |
| 107 | | `log_id` | Exact log ID (equivalent to the detail endpoint) | |
| 108 | |
| 109 | ### Operators |
| 110 | |
| 111 | | Operator | Meaning | |
| 112 | |---|---| |
| 113 | | `==` | Exact match | |
| 114 | | `!=` | Not equal | |
| 115 | | `contains` | Substring match | |
| 116 | | `not_contains` | Substring does not match | |
| 117 | |
| 118 | ### Parameters |
| 119 | |
| 120 | | Field | Type | Default | Notes | |
| 121 | |---|---|---|---| |
| 122 | | `limit` | number | `20` | Max 100 | |
| 123 | | `cursor` | string \| null | `null` | Opaque pagination token from previous response | |
| 124 | | `filters` | array | `[]` | AND-combined | |
| 125 | | `time_range.from` | number | — | Epoch milliseconds | |
| 126 | | `time_range.to` | number | — | Epoch milliseconds | |
| 127 | |
| 128 | ## Get a single log |
| 129 | |
| 130 | Fetch one log by ID to get the **full** payload, including request/response bodies, timing breakdowns, and source metadata: |
| 131 | |
| 132 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 133 | <Tab value="Python"> |
| 134 | ```python |
| 135 | from composio import Composio |
| 136 | |
| 137 | composio = Composio() |
| 138 | |
| 139 | log = composio.logs.get("log_-jRTWClpBoVo") |
| 140 | print(log.status, log.data) |
| 141 | ``` |
| 142 | </Tab> |
| 143 | <Tab value="TypeScript"> |
| 144 | ```typescript |
| 145 | import { Composio } from '@composio/core'; |
| 146 | |
| 147 | const composio = new Composio(); |
| 148 | |
| 149 | const log = await composio.logs.get('log_-jRTWClpBoVo'); |
| 150 | console.log(log.status, log.data); |
| 151 | ``` |
| 152 | </Tab> |
| 153 | <Tab value="API"> |
| 154 | ```bash |
| 155 | curl -X GET https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \ |
| 156 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 157 | ``` |
| 158 | </Tab> |
| 159 | </Tabs> |
| 160 | |
| 161 | The detail response includes everything from the list shape plus: |
| 162 | |
| 163 | - `timings`: `start_time` and `end_time` in epoch ms |
| 164 | - `context`: `session_id`, `trace_id`, `request_id` |
| 165 | - `source`: `host` (e.g. `mcp`, `sdk`, `api`), `framework`, `language` |
| 166 | - `data`: the full request payload and response body |
| 167 | |
| 168 | This is the endpoint to call when you need to reconstruct *exactly* what happened, for example when debugging a 500 from a user report. |
| 169 | |
| 170 | ## Recipes |
| 171 | |
| 172 | ### Find failed Gmail tool calls in the last hour |
| 173 | |
| 174 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 175 | <Tab value="Python"> |
| 176 | ```python |
| 177 | import time |
| 178 | |
| 179 | from composio import Composio |
| 180 | |
| 181 | composio = Composio() |
| 182 | |
| 183 | now = int(time.time() * 1000) |
| 184 | page = composio.logs.search( |
| 185 | time_range={"from": now - 3_600_000, "to": now}, |
| 186 | filters=[ |
| 187 | {"field": "toolkit_slug", "operator": "==", "value": "gmail"}, |
| 188 | {"field": "status", "operator": "==", "value": "failed"}, |
| 189 | ], |
| 190 | ) |
| 191 | ``` |
| 192 | </Tab> |
| 193 | <Tab value="TypeScript"> |
| 194 | ```typescript |
| 195 | import { Composio } from '@composio/core'; |
| 196 | |
| 197 | const composio = new Composio(); |
| 198 | |
| 199 | const now = Date.now(); |
| 200 | const { logs } = await composio.logs.search({ |
| 201 | timeRange: { from: now - 3_600_000, to: now }, |
| 202 | filters: [ |
| 203 | { field: 'toolkit_slug', operator: '==', value: 'gmail' }, |
| 204 | { field: 'status', operator: '==', value: 'failed' }, |
| 205 | ], |
| 206 | }); |
| 207 | ``` |
| 208 | </Tab> |
| 209 | <Tab value="API"> |
| 210 | ```bash |
| 211 | NOW=$(date +%s)000 |
| 212 | HOUR_AGO=$(( $(date +%s) - 3600 ))000 |
| 213 | curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \ |
| 214 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 215 | -H "Content-Type: application/json" \ |
| 216 | -d '{ |
| 217 | "time_range": { "from": '"$HOUR_AGO"', "to": '"$NOW"' }, |
| 218 | "filters": [ |
| 219 | { "field": "toolkit_slug", "operator": "==", "value": "gmail" }, |
| 220 | { "field": "status", "operator": "==", "value": "failed" } |
| 221 | ] |
| 222 | }' |
| 223 | ``` |
| 224 | </Tab> |
| 225 | </Tabs> |
| 226 | |
| 227 | ### Get failures for a specific user |
| 228 | |
| 229 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 230 | <Tab value="Python"> |
| 231 | ```python |
| 232 | from composio import Composio |
| 233 | |
| 234 | composio = Composio() |
| 235 | |
| 236 | page = composio.logs.search( |
| 237 | filters=[ |
| 238 | {"field": "user_id", "operator": "==", "value": "user_abc123"}, |
| 239 | {"field": "status", "operator": "==", "value": "failed"}, |
| 240 | ], |
| 241 | ) |
| 242 | ``` |
| 243 | </Tab> |
| 244 | <Tab value="TypeScript"> |
| 245 | ```typescript |
| 246 | import { Composio } from '@composio/core'; |
| 247 | |
| 248 | const composio = new Composio(); |
| 249 | |
| 250 | const { logs } = await composio.logs.search({ |
| 251 | filters: [ |
| 252 | { field: 'user_id', operator: '==', value: 'user_abc123' }, |
| 253 | { field: 'status', operator: '==', value: 'failed' }, |
| 254 | ], |
| 255 | }); |
| 256 | ``` |
| 257 | </Tab> |
| 258 | <Tab value="API"> |
| 259 | ```bash |
| 260 | curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \ |
| 261 | -H "x-api-key: $COMPOSIO_API_KEY" \ |
| 262 | -H "Content-Type: application/json" \ |
| 263 | -d '{ |
| 264 | "filters": [ |
| 265 | { "field": "user_id", "operator": "==", "value": "user_abc123" }, |
| 266 | { "field": "status", "operator": "==", "value": "failed" } |
| 267 | ] |
| 268 | }' |
| 269 | ``` |
| 270 | </Tab> |
| 271 | </Tabs> |
| 272 | |
| 273 | ### Fetch a single log's full request/response |
| 274 | |
| 275 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 276 | <Tab value="Python"> |
| 277 | ```python |
| 278 | from composio import Composio |
| 279 | |
| 280 | composio = Composio() |
| 281 | |
| 282 | log = composio.logs.get("log_-jRTWClpBoVo") |
| 283 | print(log.status, log.data) |
| 284 | ``` |
| 285 | </Tab> |
| 286 | <Tab value="TypeScript"> |
| 287 | ```typescript |
| 288 | import { Composio } from '@composio/core'; |
| 289 | |
| 290 | const composio = new Composio(); |
| 291 | |
| 292 | const log = await composio.logs.get('log_-jRTWClpBoVo'); |
| 293 | console.log(log.status, log.data); |
| 294 | ``` |
| 295 | </Tab> |
| 296 | <Tab value="API"> |
| 297 | ```bash |
| 298 | curl -X GET https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \ |
| 299 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 300 | ``` |
| 301 | </Tab> |
| 302 | </Tabs> |
| 303 | |
| 304 | ## Endpoints |
| 305 | |
| 306 | <ApiEndpointsTable endpoints={[{"method":"POST","pathV31":"/api/v3.1/logs/tool_execution","pathV3":"/api/v3/logs/tool_execution","summary":"Search and retrieve tool execution logs","href":"/reference/api-reference/logs/postLogsToolExecution"},{"method":"GET","pathV31":"/api/v3.1/logs/tool_execution/{id}","pathV3":"/api/v3/logs/tool_execution/{id}","summary":"Get log details by ID","href":"/reference/api-reference/logs/getLogsToolExecutionById"}]} /> |