> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs

> Logging and monitoring

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](https://composio-preview.mintlify.site/reference/api-reference/organization) instead.

All endpoints in this section require a **project API key** (`x-api-key`) or a valid session cookie.

## List logs

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> page = composio.logs.search(
>     limit=20,
>     time_range={"from": 1744848000000, "to": 1744934400000},
>     filters=[
>         {"field": "toolkit_slug", "operator": "==", "value": "gmail"},
>         {"field": "status", "operator": "==", "value": "failed"},
>     ],
> )
> print(page.logs, page.next_cursor)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const { logs, nextCursor } = await composio.logs.search({
>   limit: 20,
>   timeRange: { from: 1744848000000, to: 1744934400000 },
>   filters: [
>     { field: 'toolkit_slug', operator: '==', value: 'gmail' },
>     { field: 'status', operator: '==', value: 'failed' },
>   ],
> });
> console.log(logs, nextCursor);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
>   -H "x-api-key: $COMPOSIO_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 theme={null}
{
  "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:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> log = composio.logs.get("log_-jRTWClpBoVo")
> print(log.status, log.data)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const log = await composio.logs.get('log_-jRTWClpBoVo');
> console.log(log.status, log.data);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
>   -H "x-api-key: $COMPOSIO_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, for example when debugging a 500 from a user report.

## Recipes

### Find failed Gmail tool calls in the last hour

> [tab] Python
>
> ```python theme={null}
> import time
>
> from composio import Composio
>
> composio = Composio()
>
> now = int(time.time() * 1000)
> page = composio.logs.search(
>     time_range={"from": now - 3_600_000, "to": now},
>     filters=[
>         {"field": "toolkit_slug", "operator": "==", "value": "gmail"},
>         {"field": "status", "operator": "==", "value": "failed"},
>     ],
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const now = Date.now();
> const { logs } = await composio.logs.search({
>   timeRange: { from: now - 3_600_000, to: now },
>   filters: [
>     { field: 'toolkit_slug', operator: '==', value: 'gmail' },
>     { field: 'status', operator: '==', value: 'failed' },
>   ],
> });
> ```

> [tab] API
>
> ```bash theme={null}
> 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: $COMPOSIO_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

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> page = composio.logs.search(
>     filters=[
>         {"field": "user_id", "operator": "==", "value": "user_abc123"},
>         {"field": "status", "operator": "==", "value": "failed"},
>     ],
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const { logs } = await composio.logs.search({
>   filters: [
>     { field: 'user_id', operator: '==', value: 'user_abc123' },
>     { field: 'status', operator: '==', value: 'failed' },
>   ],
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/logs/tool_execution \
>   -H "x-api-key: $COMPOSIO_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

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> log = composio.logs.get("log_-jRTWClpBoVo")
> print(log.status, log.data)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
>
> const log = await composio.logs.get('log_-jRTWClpBoVo');
> console.log(log.status, log.data);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/logs/tool_execution/log_-jRTWClpBoVo \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```
