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

next
mdx 295 lines 7.92 KB
Raw
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>