@devries-cameron20 / composio Mirror · read-only
Fork 0

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

next
mdx 363 lines 9.48 KB
Raw
1 The Usage API returns **aggregated counts** of tool calls and sessions. Use it to power billing dashboards, customer-facing analytics, or internal utilization reports. For individual events, use the [Logs API](/reference/api-reference/logs).
2
3 There are two query shapes:
4
5 - **Summary**: totals across one or more entity types in a time window.
6 - **Breakdown**: one entity type, grouped by a dimension (tool, user, session, etc.).
7
8 Each shape comes in an org-scoped and a project-scoped flavor. The org-scoped endpoints are documented below; the project-scoped usage endpoints (`POST /api/v3.1/project/usage/*`) also appear on the [Projects](/reference/api-reference/projects) reference page.
9
10 ## Authentication
11
12 | Endpoint | Header | Scope |
13 |---|---|---|
14 | `POST /api/v3.1/org/usage/summary` | `x-org-api-key` *(or org JWT)* | All projects in your org |
15 | `POST /api/v3.1/org/usage/{entity_type}` | `x-org-api-key` *(or org JWT)* | All projects in your org |
16 | `POST /api/v3.1/project/usage/summary` | `x-api-key` *(or cookie)* | Single project |
17 | `POST /api/v3.1/project/usage/{entity_type}` | `x-api-key` *(or cookie)* | Single project |
18
19 The org endpoints accept a `project_id` filter so you can slice by project without rotating keys.
20
21 ## Entity types
22
23 | Entity type | What it counts |
24 |---|---|
25 | `tool_calls` | Every tool execution (successful or failed) |
26 | `sessions` | Sessions created |
27
28 ## Summary
29
30 Totals across entity types for a time window.
31
32 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
33 <Tab value="Python">
34 ```python
35 from composio import Composio
36
37 composio = Composio()
38
39 summary = composio.experimental.usage.summary(
40 from_=1744848000000,
41 to=1744934400000,
42 entity_types=["tool_calls", "sessions"],
43 )
44 print(summary.entities)
45 ```
46 </Tab>
47 <Tab value="TypeScript">
48 ```typescript
49 import { Composio } from '@composio/core';
50
51 const composio = new Composio();
52
53 const summary = await composio.experimental.usage.summary({
54 from: 1744848000000,
55 to: 1744934400000,
56 entityTypes: ['tool_calls', 'sessions'],
57 });
58 console.log(summary.entities);
59 ```
60 </Tab>
61 <Tab value="API">
62 ```bash
63 curl -X POST https://backend.composio.dev/api/v3.1/project/usage/summary \
64 -H "x-api-key: $COMPOSIO_API_KEY" \
65 -H "Content-Type: application/json" \
66 -d '{
67 "from": 1744848000000,
68 "to": 1744934400000,
69 "entity_types": ["tool_calls", "sessions"]
70 }'
71 ```
72 </Tab>
73 </Tabs>
74
75 Response:
76
77 ```json
78 {
79 "entities": {
80 "tool_calls": { "unit": "count", "total_quantity": "142", "event_count": 142 },
81 "sessions": { "unit": "count", "total_quantity": "8", "event_count": 8 }
82 }
83 }
84 ```
85
86 ### Summary parameters
87
88 | Field | Type | Default | Notes |
89 |---|---|---|---|
90 | `from` | number | 30 days ago | Epoch milliseconds |
91 | `to` | number | now | Epoch milliseconds |
92 | `entity_types` | string[] | all | Subset of `tool_calls`, `sessions` |
93 | `filters.user_id` | string[] | — | Filter events by initiating user |
94 | `filters.session_id` | string[] | — | Filter events by session |
95 | `filters.project_id` | string[] | — | Only meaningful on org endpoints; ignored on project endpoints |
96
97 ## Breakdown
98
99 One entity type, grouped by a dimension. Useful for answering "top N" questions.
100
101 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
102 <Tab value="Python">
103 ```python
104 from composio import Composio
105
106 composio = Composio()
107
108 breakdown = composio.experimental.usage.breakdown(
109 "tool_calls",
110 from_=1744848000000,
111 to=1744934400000,
112 group_by="toolkit_slug",
113 order_by="total_quantity",
114 order_direction="desc",
115 limit=10,
116 )
117 print(breakdown.groups)
118 ```
119 </Tab>
120 <Tab value="TypeScript">
121 ```typescript
122 import { Composio } from '@composio/core';
123
124 const composio = new Composio();
125
126 const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
127 from: 1744848000000,
128 to: 1744934400000,
129 groupBy: 'toolkit_slug',
130 orderBy: 'total_quantity',
131 orderDirection: 'desc',
132 limit: 10,
133 });
134 console.log(breakdown.groups);
135 ```
136 </Tab>
137 <Tab value="API">
138 ```bash
139 curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
140 -H "x-api-key: $COMPOSIO_API_KEY" \
141 -H "Content-Type: application/json" \
142 -d '{
143 "from": 1744848000000,
144 "to": 1744934400000,
145 "group_by": "toolkit_slug",
146 "order_by": "total_quantity",
147 "order_direction": "desc",
148 "limit": 10
149 }'
150 ```
151 </Tab>
152 </Tabs>
153
154 Response:
155
156 ```json
157 {
158 "entity_type": "tool_calls",
159 "unit": "count",
160 "total_quantity": "142",
161 "event_count": 142,
162 "groups": [
163 { "key": "github", "total_quantity": "80", "event_count": 80 },
164 { "key": "slack", "total_quantity": "62", "event_count": 62 }
165 ]
166 }
167 ```
168
169 ### Breakdown `group_by` options
170
171 | Entity | Org scope | Project scope | Default |
172 |---|---|---|---|
173 | `tool_calls` | `tool_slug`, `toolkit_slug`, `connected_account_id`, `user_id`, `session_id`, `project_id` | same minus `project_id` | `tool_slug` |
174 | `sessions` | `user_id`, `project_id` | `user_id` | `user_id` |
175
176 ### Breakdown parameters
177
178 | Field | Type | Default | Notes |
179 |---|---|---|---|
180 | `from` | number | 30 days ago | Epoch ms |
181 | `to` | number | now | Epoch ms |
182 | `group_by` | string | see table | Dimension to group by |
183 | `order_by` | string | `total_quantity` | One of `key`, `total_quantity`, `event_count` |
184 | `order_direction` | `"asc"` \| `"desc"` | `"desc"` | |
185 | `limit` | number | 50 | Max groups returned |
186 | `filters` | object | — | See Filters below |
187
188 ## Filters
189
190 Filters live in a `filters` object on the request body. Each filter value is an **array of strings**, even for a single value:
191
192 - Within a single field, values are OR-combined (`user_id: ["a", "b"]` matches events for user *a or b*).
193 - Across fields, filters are AND-combined.
194
195 ```json
196 {
197 "filters": {
198 "user_id": ["user_123", "user_456"],
199 "session_id": ["sess_abc"]
200 }
201 }
202 ```
203
204 The `project_id` filter is only meaningful on the org-scoped endpoints. Project endpoints accept the field but ignore it (your key already pins the scope to a single project).
205
206 ## Time ranges
207
208 - `from` and `to` are **epoch milliseconds**.
209 - `from` defaults to 30 days before `to`.
210 - `to` defaults to the current time.
211 - Maximum range: **366 days**. Longer ranges return a 400.
212
213 ## Recipes
214
215 ### Top 10 tools my org called last week
216
217 The Python SDK requires `COMPOSIO_API_KEY` to initialize as well as `COMPOSIO_ORG_API_KEY` for the organization-scoped request.
218
219 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
220 <Tab value="Python">
221 ```python
222 import os
223 import time
224 from composio import Composio
225
226 composio = Composio(org_api_key=os.environ["COMPOSIO_ORG_API_KEY"])
227 now = int(time.time()) * 1000
228 breakdown = composio.client.org.usage.retrieve(
229 "tool_calls",
230 from_=now - 604_800_000,
231 to=now,
232 group_by="tool_slug",
233 limit=10,
234 )
235 print(breakdown)
236 ```
237 </Tab>
238 <Tab value="TypeScript">
239 ```typescript
240 import { Composio } from '@composio/core';
241
242 const composio = new Composio({
243 apiKey: null,
244 userApiKey: null,
245 orgApiKey: process.env.COMPOSIO_ORG_API_KEY,
246 });
247 const now = Math.floor(Date.now() / 1000) * 1000;
248 const breakdown = await composio.getClient().post<unknown>('/api/v3.1/org/usage/tool_calls', {
249 body: { from: now - 604_800_000, to: now, group_by: 'tool_slug', limit: 10 },
250 });
251 console.log(breakdown);
252 ```
253 </Tab>
254 <Tab value="API">
255 ```bash
256 WEEK_AGO=$(( $(date +%s) - 604800 ))000
257 NOW=$(date +%s)000
258 curl -X POST https://backend.composio.dev/api/v3.1/org/usage/tool_calls \
259 -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" \
260 -H "Content-Type: application/json" \
261 -d '{
262 "from": '"$WEEK_AGO"',
263 "to": '"$NOW"',
264 "group_by": "tool_slug",
265 "limit": 10
266 }'
267 ```
268 </Tab>
269 </Tabs>
270
271 ### Tool call count per user for my project this month
272
273 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
274 <Tab value="Python">
275 ```python
276 import time
277
278 from composio import Composio
279
280 composio = Composio()
281
282 now = int(time.time() * 1000)
283 breakdown = composio.experimental.usage.breakdown(
284 "tool_calls",
285 from_=now - 2_592_000_000,
286 to=now,
287 group_by="user_id",
288 limit=50,
289 )
290 ```
291 </Tab>
292 <Tab value="TypeScript">
293 ```typescript
294 import { Composio } from '@composio/core';
295
296 const composio = new Composio();
297
298 const now = Date.now();
299 const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
300 from: now - 2_592_000_000,
301 to: now,
302 groupBy: 'user_id',
303 limit: 50,
304 });
305 ```
306 </Tab>
307 <Tab value="API">
308 ```bash
309 MONTH_AGO=$(( $(date +%s) - 2592000 ))000
310 NOW=$(date +%s)000
311 curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
312 -H "x-api-key: $COMPOSIO_API_KEY" \
313 -H "Content-Type: application/json" \
314 -d '{
315 "from": '"$MONTH_AGO"',
316 "to": '"$NOW"',
317 "group_by": "user_id",
318 "limit": 50
319 }'
320 ```
321 </Tab>
322 </Tabs>
323
324 ### Which toolkits is a specific user using?
325
326 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
327 <Tab value="Python">
328 ```python
329 from composio import Composio
330
331 composio = Composio()
332
333 breakdown = composio.experimental.usage.breakdown(
334 "tool_calls",
335 group_by="toolkit_slug",
336 filters={"user_id": ["user_abc123"]},
337 )
338 ```
339 </Tab>
340 <Tab value="TypeScript">
341 ```typescript
342 import { Composio } from '@composio/core';
343
344 const composio = new Composio();
345
346 const breakdown = await composio.experimental.usage.breakdown('tool_calls', {
347 groupBy: 'toolkit_slug',
348 filters: { userId: ['user_abc123'] },
349 });
350 ```
351 </Tab>
352 <Tab value="API">
353 ```bash
354 curl -X POST https://backend.composio.dev/api/v3.1/project/usage/tool_calls \
355 -H "x-api-key: $COMPOSIO_API_KEY" \
356 -H "Content-Type: application/json" \
357 -d '{
358 "group_by": "toolkit_slug",
359 "filters": { "user_id": ["user_abc123"] }
360 }'
361 ```
362 </Tab>
363 </Tabs>