@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, 04:45 UTC

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