@devries-cameron20 / composio-1 / commits / ae3c06914
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.

fix(core): align usage and log charges with Instant API (#4693)

## Summary Follow up on merged SDK PR #4651 to match the Instant names in [platform PR #13432](https://github.com/ComposioHQ/platform/pull/13432) ([PLEN-4181](https://linear.app/composio/issue/PLEN-4181/update-api-contract-to-new-names)). The summary charge remains a top-level sibling of `entities`. ## Changes - Rename the TypeScript summary field to `instantCharge` and the Python field to `instant_charge`. - Rename typed tool-log metadata to `metadata.instant_charge`, keeping the exact USD string and optional charge behavior. - Update regression tests, API documentation, and the core changeset. No old-name aliases are added. ## Type of change - [x] Bug fix - [x] Breaking change - [x] Documentation ## How Has This Been Tested? - TypeScript: 14 focused usage/log tests; `@composio/core` typecheck; Oxlint. - Python: 10 focused usage/log tests; Ruff check and formatting with the repository config. - Docs: 608 static tests; lint (existing warnings), link validation, typecheck, full production build, semantic artifact check with `--allow-stale`. - Changeset validation and `git diff --check`. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I have read and understand every line of this diff, including any LLM-generated code - [x] Any third-party docs links or promotional content follow the third-party links policy - [x] I ran linters/tests locally and they passed - [x] I updated documentation as needed - [x] I added tests or explain why not applicable - [x] I added a changeset if this change affects published packages ## Additional context #4651 is already merged, so this is its follow-up. Stacked child: #4694 covers session configuration, account selectors, and execution-contract renames. Merge this PR first, then retarget #4694 to `next`. Published generated clients still use the old names; SDK-owned response schemas consume the new fields without modifying generated code. --------- Co-authored-by: jkomyno <alberto@composio.dev>

Prachi Mandil committed Sep 29, 2026 at 19:57 UTC ae3c06914dba8ee39b1f8db4614caa9efbe06f3e
16 files changed +59 -79
.changeset/instant-usage-response-contract.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +"@composio/core": minor
3 +---
4 +
5 +Expose the exact Instant charge as `instantCharge` in project usage summaries and as `metadata.instant_charge` in tool log metadata.
.changeset/premium-usage-response-contract.md deleted
-5
@@ -1,5 +0,0 @@
1 ----
2 -'@composio/core': minor
3 ----
4 -
5 -Expose the exact premium usage charge in project usage summaries and tool log metadata.
docs/content/docs/poc-to-prod/stream-logs-to-a-siem.mdx
+1 -1
@@ -40,7 +40,7 @@ Both SDKs expose `composio.logs.search()` for read-only searches with filters, a
40
41 Retrieve the full entry for one execution with `composio.logs.get("log_123")` in Python or `await composio.logs.get('log_123')` in TypeScript.
42
43 -For a charged hosted-account call, both the search result and the full entry include `metadata.premium_usage_charge` as an exact USD string. The field is absent when the call has no premium charge.
43 +For a charged Instant-account call, both the search result and the full entry include `metadata.instant_charge` as an exact USD string. The field is absent when the call has no Instant charge.
44
45 ## Schedule collection without losing your place
46
docs/content/docs/production-readiness.mdx
+1 -1
@@ -86,7 +86,7 @@ In Python, pass a standard `logging.Logger` as `logger` and a `composio.utils.lo
86
87 Use `composio.experimental.usage.summary()` for totals by entity type and `composio.experimental.usage.breakdown()` for grouped usage of one entity type, such as `tool_calls` or `sessions`. Both SDKs scope these queries to the project associated with your API key.
88
89 -The summary also returns the total premium usage charge for the window as an exact USD string: `premiumUsageCharge` in TypeScript and `premium_usage_charge` in Python. It returns `"0"` when no usage was charged. Breakdowns contain usage quantities and event counts, not charges.
89 +The summary also returns the total Instant charge for the window as an exact USD string: `instantCharge` in TypeScript and `instant_charge` in Python. It returns `"0"` when no usage was charged. Breakdowns contain usage quantities and event counts, not charges.
90
91 <Callout>
92 Usage metering is experimental, and its response shape may change.
docs/public/openapi.json
+16 -36
@@ -12624,23 +12624,23 @@
12624 "event_count": {
12625 "type": "integer",
12626 "minimum": 0
12627 - },
12628 - "premium_usage_charge": {
12629 - "type": "string",
12630 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12627 }
12628 },
12629 "required": [
12630 "unit",
12631 "total_quantity",
12636 - "event_count",
12637 - "premium_usage_charge"
12632 + "event_count"
12633 ]
12634 }
12635 + },
12636 + "instant_charge": {
12637 + "type": "string",
12638 + "description": "Total Instant charge over this window, as an exact USD amount. Zero when nothing in it was charged."
12639 }
12640 },
12641 "required": [
12643 - "entities"
12642 + "entities",
12643 + "instant_charge"
12644 ]
12645 }
12646 }
@@ -12824,10 +12824,6 @@
12824 "type": "integer",
12825 "minimum": 0
12826 },
12827 - "premium_usage_charge": {
12828 - "type": "string",
12829 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12830 - },
12827 "groups": {
12828 "type": "array",
12829 "items": {
@@ -12842,17 +12838,12 @@
12838 "event_count": {
12839 "type": "integer",
12840 "minimum": 0
12845 - },
12846 - "premium_usage_charge": {
12847 - "type": "string",
12848 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
12841 }
12842 },
12843 "required": [
12844 "key",
12845 "total_quantity",
12854 - "event_count",
12855 - "premium_usage_charge"
12846 + "event_count"
12847 ]
12848 }
12849 }
@@ -12862,7 +12853,6 @@
12853 "unit",
12854 "total_quantity",
12855 "event_count",
12865 - "premium_usage_charge",
12856 "groups"
12857 ]
12858 }
@@ -13007,23 +12997,23 @@
12997 "event_count": {
12998 "type": "integer",
12999 "minimum": 0
13010 - },
13011 - "premium_usage_charge": {
13012 - "type": "string",
13013 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13000 }
13001 },
13002 "required": [
13003 "unit",
13004 "total_quantity",
13019 - "event_count",
13020 - "premium_usage_charge"
13005 + "event_count"
13006 ]
13007 }
13008 + },
13009 + "instant_charge": {
13010 + "type": "string",
13011 + "description": "Total Instant charge over this window, as an exact USD amount. Zero when nothing in it was charged."
13012 }
13013 },
13014 "required": [
13026 - "entities"
13015 + "entities",
13016 + "instant_charge"
13017 ]
13018 }
13019 }
@@ -13198,10 +13188,6 @@
13188 "type": "integer",
13189 "minimum": 0
13190 },
13201 - "premium_usage_charge": {
13202 - "type": "string",
13203 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13204 - },
13191 "groups": {
13192 "type": "array",
13193 "items": {
@@ -13216,17 +13202,12 @@
13202 "event_count": {
13203 "type": "integer",
13204 "minimum": 0
13219 - },
13220 - "premium_usage_charge": {
13221 - "type": "string",
13222 - "description": "Total charge for premium usage in this aggregate, as an exact USD amount. Zero when nothing in it was charged."
13205 }
13206 },
13207 "required": [
13208 "key",
13209 "total_quantity",
13228 - "event_count",
13229 - "premium_usage_charge"
13210 + "event_count"
13211 ]
13212 }
13213 }
@@ -13236,7 +13217,6 @@
13217 "unit",
13218 "total_quantity",
13219 "event_count",
13239 - "premium_usage_charge",
13220 "groups"
13221 ]
13222 }
python/composio/core/models/experimental.py
+3 -3
@@ -52,9 +52,9 @@ ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT = "acl_config_for_shared is only valid on SHA
52 class UsageSummaryResponse(
53 usage_retrieve_summary_response.UsageRetrieveSummaryResponse
54 ):
55 - """Project usage summary with the exact USD premium charge for the window."""
55 + """Project usage summary with the exact USD Instant charge for the window."""
56
57 - premium_usage_charge: str
57 + instant_charge: str
58
59
60 class ExperimentalUsage:
@@ -89,7 +89,7 @@ class ExperimentalUsage:
89 :param entity_types: Restrict the summary to these entity types.
90 :param filters: Additional server-side filters.
91 :return: Usage totals under ``.entities`` and the exact USD amount in
92 - ``.premium_usage_charge`` (``"0"`` when nothing was charged).
92 + ``.instant_charge`` (``"0"`` when nothing was charged).
93
94 Example:
95 summary = composio.experimental.usage.summary(
python/composio/core/models/logs.py
+2 -2
@@ -36,7 +36,7 @@ class Logs(Resource):
36 :param time_range: Time window to search within.
37 :return: Matching logs plus a ``next_cursor`` for pagination. A charged
38 tool log has an exact USD string at
39 - ``log.metadata["premium_usage_charge"]``.
39 + ``log.metadata["instant_charge"]``.
40
41 Example:
42 page = composio.logs.search(
@@ -58,7 +58,7 @@ class Logs(Resource):
58
59 :param id: The log id.
60 :return: The full log entry. For charged calls,
61 - ``log.metadata["premium_usage_charge"]`` is the exact USD amount.
61 + ``log.metadata["instant_charge"]`` is the exact USD amount.
62
63 Example:
64 log = composio.logs.get("log_123")
python/tests/test_experimental_usage.py
+4 -4
@@ -32,7 +32,7 @@ class TestExperimentalUsage:
32 def test_summary_passes_params_through(self, usage, mock_client):
33 mock_client.project.usage.retrieve_summary.return_value = (
34 usage_retrieve_summary_response.UsageRetrieveSummaryResponse.model_validate(
35 - {"entities": {}, "premium_usage_charge": "0.025"}
35 + {"entities": {}, "instant_charge": "0.025"}
36 )
37 )
38
@@ -44,7 +44,7 @@ class TestExperimentalUsage:
44 )
45
46 assert result.entities == {}
47 - assert result.premium_usage_charge == "0.025"
47 + assert result.instant_charge == "0.025"
48 mock_client.project.usage.retrieve_summary.assert_called_once_with(
49 from_=1.0,
50 to=2.0,
@@ -55,14 +55,14 @@ class TestExperimentalUsage:
55 def test_summary_without_params(self, usage, mock_client):
56 mock_client.project.usage.retrieve_summary.return_value = (
57 usage_retrieve_summary_response.UsageRetrieveSummaryResponse.model_validate(
58 - {"entities": {}, "premium_usage_charge": "0"}
58 + {"entities": {}, "instant_charge": "0"}
59 )
60 )
61
62 result = usage.summary()
63
64 mock_client.project.usage.retrieve_summary.assert_called_once_with()
65 - assert result.premium_usage_charge == "0"
65 + assert result.instant_charge == "0"
66
67 def test_breakdown_passes_entity_type_and_params(self, usage, mock_client):
68 mock_client.project.usage.retrieve.return_value = "breakdown"
python/tests/test_logs.py
+6 -6
@@ -25,7 +25,7 @@ def logs(mock_client: Mock) -> Logs:
25
26
27 class TestLogs:
28 - def test_search_preserves_premium_usage_charge(self, logs, mock_client):
28 + def test_search_preserves_instant_charge(self, logs, mock_client):
29 mock_client.logs.create_tool_execution.return_value = log_create_tool_execution_response.LogCreateToolExecutionResponse.model_validate(
30 {
31 "logs": [
@@ -35,7 +35,7 @@ class TestLogs:
35 "type": "tool.execution",
36 "status": "success",
37 "level": "info",
38 - "metadata": {"premium_usage_charge": "0.012"},
38 + "metadata": {"instant_charge": "0.012"},
39 "metrics": {},
40 "parent": None,
41 }
@@ -46,7 +46,7 @@ class TestLogs:
46
47 result = logs.search()
48
49 - assert result.logs[0].metadata["premium_usage_charge"] == "0.012"
49 + assert result.logs[0].metadata["instant_charge"] == "0.012"
50
51 def test_search_passes_params_through(self, logs, mock_client):
52 mock_client.logs.create_tool_execution.return_value = "page"
@@ -77,7 +77,7 @@ class TestLogs:
77 assert logs.get("log_123") == "log"
78 mock_client.logs.retrieve_tool_execution.assert_called_once_with("log_123")
79
80 - def test_get_preserves_premium_usage_charge(self, logs, mock_client):
80 + def test_get_preserves_instant_charge(self, logs, mock_client):
81 mock_client.logs.retrieve_tool_execution.return_value = log_retrieve_tool_execution_response.LogRetrieveToolExecutionResponse.model_validate(
82 {
83 "id": "log_1",
@@ -85,7 +85,7 @@ class TestLogs:
85 "type": "tool.execution",
86 "status": "success",
87 "level": "info",
88 - "metadata": {"premium_usage_charge": "0.012"},
88 + "metadata": {"instant_charge": "0.012"},
89 "metrics": {},
90 "parent": None,
91 "context": {},
@@ -96,4 +96,4 @@ class TestLogs:
96
97 result = logs.get("log_1")
98
99 - assert result.metadata["premium_usage_charge"] == "0.012"
99 + assert result.metadata["instant_charge"] == "0.012"
ts/packages/core/src/models/Logs.ts
+2 -2
@@ -46,7 +46,7 @@ export class Logs {
46 * pagination.
47 *
48 * @param {LogSearchParams} [params] - Filters, `timeRange`, `limit` and `cursor`
49 - * @returns {Promise<LogSearchResponse>} Matching logs and the next cursor. Charged calls include `metadata.premium_usage_charge` as an exact USD string.
49 + * @returns {Promise<LogSearchResponse>} Matching logs and the next cursor. Charged calls include `metadata.instant_charge` as an exact USD string.
50 * @throws {ValidationError} If the params fail validation
51 *
52 * @example
@@ -83,7 +83,7 @@ export class Logs {
83 * source and raw `data`).
84 *
85 * @param {string} id - The log id
86 - * @returns {Promise<ToolExecutionLogDetail>} The log detail, with an optional exact USD charge in `metadata.premium_usage_charge`
86 + * @returns {Promise<ToolExecutionLogDetail>} The log detail, with an optional exact USD charge in `metadata.instant_charge`
87 *
88 * @example
89 * ```typescript
ts/packages/core/src/models/Usage.ts
+2 -2
@@ -32,7 +32,7 @@ import {
32 * ```typescript
33 * const summary = await composio.experimental.usage.summary();
34 * console.log(summary.entities.tool_calls?.totalQuantity);
35 - * console.log(summary.premiumUsageCharge); // exact USD string
35 + * console.log(summary.instantCharge); // exact USD string
36 *
37 * const byTool = await composio.experimental.usage.breakdown('tool_calls', {
38 * groupBy: 'tool_slug',
@@ -53,7 +53,7 @@ export class Usage {
53 * **Experimental — shape may change in future releases.**
54 *
55 * @param {UsageSummaryParams} [params] - Optional range, `entityTypes` and filters
56 - * @returns {Promise<UsageSummaryResponse>} Totals keyed by entity type and the exact USD premium usage charge
56 + * @returns {Promise<UsageSummaryResponse>} Totals keyed by entity type and the exact USD Instant charge
57 * @throws {ValidationError} If the params fail validation
58 *
59 * @example
ts/packages/core/src/types/logs.types.ts
+2 -2
@@ -56,10 +56,10 @@ export const ToolExecutionLogParentSchema = z
56 })
57 .nullable();
58
59 -/** Tool log metadata, including the optional exact USD premium charge. */
59 +/** Tool log metadata, including the optional exact USD Instant charge. */
60 export const ToolExecutionLogMetadataSchema = z
61 .object({
62 - premium_usage_charge: z.string().optional(),
62 + instant_charge: z.string().optional(),
63 })
64 .catchall(z.unknown());
65 export type ToolExecutionLogMetadata = z.infer<typeof ToolExecutionLogMetadataSchema>;
ts/packages/core/src/types/usage.types.ts
+2 -2
@@ -61,8 +61,8 @@ export type UsageEntitySummary = z.infer<typeof UsageEntitySummarySchema>;
61 export const UsageSummaryResponseSchema = z.object({
62 /** Aggregates keyed by metering entity type (e.g. `tool_calls`, `sessions`). */
63 entities: z.record(z.string(), UsageEntitySummarySchema),
64 - /** Total premium usage charge for the window, in USD as an exact decimal string. */
65 - premiumUsageCharge: z.string(),
64 + /** Total Instant charge for the window, in USD as an exact decimal string. */
65 + instantCharge: z.string(),
66 });
67 export type UsageSummaryResponse = z.infer<typeof UsageSummaryResponseSchema>;
68
ts/packages/core/src/utils/transformers/usage.ts
+2 -2
@@ -44,7 +44,7 @@ export const transformUsageSummaryResponse = (
44 response: RawUsageSummaryResponse
45 ): UsageSummaryResponse => {
46 // The pinned generated client predates this response field but preserves the raw JSON.
47 - const { premium_usage_charge } = z.object({ premium_usage_charge: z.string() }).parse(response);
47 + const { instant_charge } = z.object({ instant_charge: z.string() }).parse(response);
48 return transform(response)
49 .with(UsageSummaryResponseSchema)
50 .using(response => ({
@@ -58,7 +58,7 @@ export const transformUsageSummaryResponse = (
58 },
59 ])
60 ),
61 - premiumUsageCharge: premium_usage_charge,
61 + instantCharge: instant_charge,
62 }));
63 };
64
ts/packages/core/test/models/logs.test.ts
+7 -7
@@ -26,7 +26,7 @@ const rawLog = {
26 status: 'success',
27 level: 'info',
28 message: 'ok',
29 - metadata: { tool_slug: 'GITHUB_GET_REPO', premium_usage_charge: '0.012' },
29 + metadata: { tool_slug: 'GITHUB_GET_REPO', instant_charge: '0.012' },
30 metrics: { duration_ms: 12 },
31 parent: { log_id: 'log_0', tool_slug: 'COMPOSIO_MULTI_EXECUTE_TOOL' },
32 };
@@ -37,7 +37,7 @@ const transformedLog = {
37 status: 'success',
38 level: 'info',
39 message: 'ok',
40 - metadata: { tool_slug: 'GITHUB_GET_REPO', premium_usage_charge: '0.012' },
40 + metadata: { tool_slug: 'GITHUB_GET_REPO', instant_charge: '0.012' },
41 metrics: { duration_ms: 12 },
42 parent: { logId: 'log_0', toolSlug: 'COMPOSIO_MULTI_EXECUTE_TOOL' },
43 };
@@ -102,7 +102,7 @@ describe('Logs', () => {
102 ],
103 nextCursor: 'cursor_2',
104 });
105 - expect(result.logs[0]?.metadata.premium_usage_charge).toBe('0.012');
105 + expect(result.logs[0]?.metadata.instant_charge).toBe('0.012');
106 });
107
108 it('throws a ValidationError for an unknown filter field', async () => {
@@ -114,9 +114,9 @@ describe('Logs', () => {
114 expect(mockClient.logs.createToolExecution).not.toHaveBeenCalled();
115 });
116
117 - it('rejects a non-string premium charge in log metadata', async () => {
117 + it('rejects a non-string Instant charge in log metadata', async () => {
118 mockClient.logs.createToolExecution.mockResolvedValue({
119 - logs: [{ ...rawLog, metadata: { premium_usage_charge: 0.012 } }],
119 + logs: [{ ...rawLog, metadata: { instant_charge: 0.012 } }],
120 next_cursor: null,
121 });
122
@@ -160,7 +160,7 @@ describe('Logs', () => {
160 expect(result.context).toEqual({});
161 });
162
163 - it('leaves the premium charge absent for an uncharged call', async () => {
163 + it('leaves the Instant charge absent for an uncharged call', async () => {
164 mockClient.logs.retrieveToolExecution.mockResolvedValue({
165 ...rawLog,
166 metadata: { tool_slug: 'GITHUB_GET_REPO' },
@@ -171,7 +171,7 @@ describe('Logs', () => {
171
172 const result = await logs.get('log_1');
173
174 - expect(result.metadata.premium_usage_charge).toBeUndefined();
174 + expect(result.metadata.instant_charge).toBeUndefined();
175 });
176 });
177 });
ts/packages/core/test/models/usage.test.ts
+4 -4
@@ -45,7 +45,7 @@ describe('Experimental.usage', () => {
45 it('sends an empty body when called without params', async () => {
46 mockClient.project.usage.retrieveSummary.mockResolvedValue({
47 entities: {},
48 - premium_usage_charge: '0',
48 + instant_charge: '0',
49 });
50
51 const result = await experimental.usage.summary();
@@ -54,7 +54,7 @@ describe('Experimental.usage', () => {
54 { from: undefined, to: undefined, entity_types: undefined, filters: undefined },
55 undefined
56 );
57 - expect(result).toEqual({ entities: {}, premiumUsageCharge: '0' });
57 + expect(result).toEqual({ entities: {}, instantCharge: '0' });
58 });
59
60 it('maps params to the wire and transforms the response', async () => {
@@ -63,7 +63,7 @@ describe('Experimental.usage', () => {
63 tool_calls: { unit: 'call', total_quantity: '42', event_count: 42 },
64 sessions: { unit: 'session', total_quantity: '3', event_count: 3 },
65 },
66 - premium_usage_charge: '0.025',
66 + instant_charge: '0.025',
67 });
68 const signal = new AbortController().signal;
69
@@ -91,7 +91,7 @@ describe('Experimental.usage', () => {
91 tool_calls: { unit: 'call', totalQuantity: '42', eventCount: 42 },
92 sessions: { unit: 'session', totalQuantity: '3', eventCount: 3 },
93 },
94 - premiumUsageCharge: '0.025',
94 + instantCharge: '0.025',
95 });
96 });
97