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 306 lines 8.53 KB
Raw
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"}]} />