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