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, 09:45 UTC
docs(instant): update guide for current APIs and Sessions
palash-c committed
Oct 7, 2026 at 21:34 UTC
4914fb6440414d7aeece75bccb140ebac9ca50bb
1 file changed
+141
-95
docs/content/docs/instant-tools.mdx
+141
-95
@@ -1,33 +1,23 @@
1
---
2
-title: Instant
2
+title: Instant Tools
3
description: Use supported tools in a Session without asking every user to connect a provider account
4
keywords: [Composio Instant, instant tools, Sessions, Instant usage, Instant account]
5
experimental: true
6
---
7
8
-Composio Instant gives your agent capabilities beyond what your users have connected, including web search, scraping, data enrichment, and image and video generation. We add more regularly. Supported tools run on Composio's provider accounts, so your users don't need OAuth, provider API keys, or per-provider signups. Calls through those accounts charge your Composio balance. When a task needs a user's own identity, they can still connect their account.
8
+Instant Tools give your agent capabilities beyond what your users have connected, including web search, scraping, data enrichment, and image and video generation. Supported tools run on Composio's provider accounts, so your users don't need OAuth, provider API keys, or per-provider signups. Calls through those accounts charge your Composio balance. When a task needs a user's own identity, they can still connect their account.
9
10
-<Callout type="warning" title="Experimental access">
11
- Email [support@composio.dev](mailto:support@composio.dev) to enable Instant for your project during experimental access. A Session cannot override a project where Instant is off.
12
-</Callout>
13
-
14
-Once the project setting is enabled, new Sessions can use eligible instant tools by default, even if `instant` is omitted. Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session that must not incur Instant usage charges.
15
-
16
-## Balance and failed calls
10
+Instant Tools were previously called Premium Tools.
11
18
-Developer organizations get a one-time $2 starter credit. Check your balance in [Dashboard → Organization Settings → Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). On Pro, add prepaid funds there; Hobby organizations must upgrade to Pro before adding funds. When Composio confirms that the balance is exhausted, an Instant call fails with HTTP 402 (`Metering_WalletBalanceExhausted`). It does not fall back to another account. Calls that select a user's connected account can still run. Balance verification is asynchronous, so $0 is not a strict per-call spending cap.
12
+## Enable Instant for your project
13
20
-## Find eligible tools
21
-
22
-Instant coverage is per tool, not per toolkit. A toolkit may support instant tools without every tool in it being eligible. Composio's provider account can be shared across customers, so only reviewed actions can run through it. Actions that could reveal shared account history or send arbitrary proxy requests are excluded. Use a connected account for actions Instant does not support.
14
+In [project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs&utm_medium=content&utm_campaign=instant-tools), turn on **Instant Toolkits**. Developer projects start with this setting off. A Session cannot override a project where Instant is off.
15
24
-In the dashboard, open **Toolkits** and select the filter for instant tools. An **Instant** badge on a toolkit means at least one of its tools supports Instant access. Open the toolkit to find the **Instant** badge beside each eligible tool.
25
-
26
-<Figure src="/images/instant-toolkit-filter.png" alt="Toolkits dashboard with the instant tools filter selected and Instant badges on matching toolkits" caption="Filter the toolkit catalog to find Instant support." />
27
-
28
-<Figure src="/images/instant-tool-eligibility.png" alt="Firecrawl toolkit page with Instant badges on Map multiple URLs, Scrape URL, and Search, but not on other tools" caption="Check individual tools before using an Instant account." />
16
+Once enabled, new Sessions can use eligible Instant tools by default, even if `instant` is omitted. Session restrictions can narrow this access. Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session that must not incur Instant usage charges.
17
30
-Instant eligibility and pricing discovery in the catalog APIs are coming soon. The public [toolkit listing API](/reference/api-reference/toolkits/getToolkits) does not yet return Instant availability or offer an Instant filter. Do not infer Instant support from `no_auth` or `composio_managed_auth_schemes`; they describe different access routes. During experimental access, ask [support@composio.dev](mailto:support@composio.dev) to confirm supported tools and rates.
18
+<Callout type="info" title="Experimental access">
19
+ If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
20
+</Callout>
21
22
## Create a Session
23
@@ -51,7 +41,6 @@ session = composio.sessions.create(
41
</Tab>
42
<Tab value="TypeScript">
43
```typescript
54
-// @noErrors
44
import { Composio } from "@composio/core";
45
46
const composio = new Composio();
@@ -66,95 +55,74 @@ const session = await composio.create("user_123", {
55
</Tab>
56
</Tabs>
57
69
-Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `instant.toolkits` separately restricts which eligible tools can incur Instant usage charges. Omitting `instant.toolkits` does not restrict Instant usage: eligible tools remain available when the project and Session permit them. `return_instant_charge` defaults to `false` and only controls whether the actual charge appears in the immediate tool response. A toolkit with Instant support can still contain tools that need a connected account; Instant account coverage is tool-specific.
58
+Top-level `toolkits` controls which tools the Session can discover and run. Omit it to make all toolkits discoverable. `instant.toolkits` separately restricts which eligible tools can incur Instant usage charges. Omitting `instant.toolkits` does not restrict Instant usage. Eligible tools remain available when the project and Session permit them. `return_instant_charge` defaults to `false` and only controls whether the actual charge appears in the immediate tool response.
59
71
-## Run a search with an agent
60
+## Find eligible tools
61
73
-Install `composio`, `openai-agents`, and `python-dotenv` for Python, or `@composio/core`, `@openai/agents`, `zod`, and `dotenv` for TypeScript. Put `COMPOSIO_API_KEY` and `OPENAI_API_KEY` in a `.env` file as in the [Quickstart](/docs/quickstart). This small agent can choose when to search. The wrapper prints the Instant charge after each search call:
62
+Instant coverage is per tool, not per toolkit. A toolkit may support instant tools without every tool in it being eligible. Composio's provider account can be shared across customers, so only reviewed actions can run through it. Actions that could reveal shared account history or send arbitrary proxy requests are excluded. Use a connected account for actions Instant does not support.
63
75
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
76
-<Tab value="Python">
77
-```python
78
-from agents import Agent, Runner, function_tool
79
-from composio import Composio
80
-from dotenv import load_dotenv
64
+In the dashboard, open **Toolkits** and select the filter for instant tools. An **Instant** badge on a toolkit means at least one of its tools supports Instant access. Open the toolkit to find the **Instant** badge beside each eligible tool.
65
+
66
+<Figure src="/images/instant-toolkit-filter.png" alt="Toolkits dashboard with the instant tools filter selected and Instant badges on matching toolkits" caption="Filter the toolkit catalog to find Instant support." />
67
82
-load_dotenv()
83
-session = Composio().sessions.create(user_id="user_123", toolkits=["exa"], instant={"return_instant_charge": True})
68
+<Figure src="/images/instant-tool-eligibility.png" alt="Firecrawl toolkit page with Instant badges on Map multiple URLs, Scrape URL, and Search, but not on other tools" caption="Check individual tools before using an Instant account." />
69
+
70
+### List supported toolkits
71
85
-@function_tool
86
-def search(query: str) -> str:
87
- result = session.execute("EXA_SEARCH", arguments={"query": query})
88
- print("Instant charge:", result.instant_charge or "none")
89
- return str(result.data)
72
+Use the [toolkit listing API](/reference/api-reference/toolkits/getToolkits) to fetch a page, then filter its `items` by `instant.supported`. This example uses `jq` to keep eligible toolkits and the pagination cursor:
73
91
-agent = Agent(name="Researcher", instructions="Use search when you need current information.", tools=[search])
92
-while prompt := input("You: "):
93
- print(Runner.run_sync(agent, prompt).final_output)
74
+```bash
75
+curl --get 'https://backend.composio.dev/api/v3.1/toolkits' \
76
+ --header "x-api-key: $COMPOSIO_API_KEY" \
77
+ --data-urlencode 'limit=100' \
78
+ | jq '{items: [.items[] | select(.instant.supported == true)], next_cursor}'
79
```
95
-</Tab>
96
-<Tab value="TypeScript">
97
-```typescript
98
-import "dotenv/config";
99
-import { Composio } from "@composio/core";
100
-import { Agent, run, tool } from "@openai/agents";
101
-import { createInterface } from "node:readline/promises";
102
-import { z } from "zod";
80
104
-const session = await new Composio().create("user_123", {
105
- toolkits: ["exa"],
106
- instant: { returnInstantCharge: true },
107
-});
81
+Fetch subsequent pages with `--data-urlencode "cursor=$NEXT_CURSOR"`, where `NEXT_CURSOR` is the previous response's `next_cursor`. Continue until `next_cursor` is empty or null, even if a page has no matching toolkits. A toolkit's `instant.supported` means at least one tool supports Instant, not every tool.
82
109
-const search = tool({
110
- name: "search",
111
- description: "Search the web for current information.",
112
- parameters: z.object({ query: z.string() }),
113
- execute: async ({ query }) => {
114
- const result = await session.execute("EXA_SEARCH", { query });
115
- console.log("Instant charge:", result.instantCharge ?? "none");
116
- return JSON.stringify(result.data);
117
- },
118
-});
83
+Do not infer Instant support from `no_auth` or `composio_managed_auth_schemes`. They describe different access routes.
84
120
-const agent = new Agent({
121
- name: "Researcher",
122
- instructions: "Use search when you need current information.",
123
- tools: [search],
124
-});
125
-const readline = createInterface({ input: process.stdin, output: process.stdout });
126
-try {
127
- while (true) {
128
- const prompt = await readline.question("You: ");
129
- if (!prompt) break;
130
- console.log((await run(agent, prompt)).finalOutput);
131
- }
132
-} finally {
133
- readline.close();
134
-}
85
+### Check tool eligibility and rates
86
+
87
+Request `include_pricing=true` when [listing tools](/reference/api-reference/tools/getTools) or [reading a tool](/reference/api-reference/tools/getToolsByToolSlug). Select the latest toolkit version to receive Instant metadata:
88
+
89
+```bash
90
+curl --get 'https://backend.composio.dev/api/v3.1/tools' \
91
+ --header "x-api-key: $COMPOSIO_API_KEY" \
92
+ --data-urlencode 'toolkit_slug=exa' \
93
+ --data-urlencode 'toolkit_versions=latest' \
94
+ --data-urlencode 'include_pricing=true' \
95
+ --data-urlencode 'limit=100' \
96
+ | jq '{items: [.items[] | select(.instant.supported == true) | {slug, instant}], next_cursor}'
97
+
98
+curl --get 'https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH' \
99
+ --header "x-api-key: $COMPOSIO_API_KEY" \
100
+ --data-urlencode 'toolkit_versions=latest' \
101
+ --data-urlencode 'include_pricing=true' \
102
+ | jq '{slug, instant, input_parameters}'
103
```
136
-</Tab>
137
-</Tabs>
104
139
-The charge is present only if an Instant account served the call. A connected-account call prints `none`. Check the [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) if you change tools or arguments.
105
+Follow `next_cursor` on tool listings as you do for toolkits. Eligible tools include `instant.supported: true`. When published pricing is available, `instant.price.description` contains the human-readable rate and `instant.price.discount` contains the discount. Both values are strings when present, and `discount` can be null. Do not treat them as numeric prices or infer an expiry date. Discounts may change.
106
+
107
+Missing pricing does not mean a tool is free. Check the rate before running it. Instant metadata is absent for older toolkit versions and ineligible tools.
108
141
-## Find and run other tools
109
+## Use Session tools
110
143
-Pass `session.tools()` to your agent as in the [Quickstart](/docs/quickstart), so it can discover and run eligible tools. If your agent uses MCP, expose the same Session through `session.mcp` as described in [Using sessions via MCP](/docs/sessions-via-mcp). The Instant usage policy applies to that Session in either path; your agent does not need a separate Instant usage setting.
111
+Pass `session.tools()` to your agent as in the [Quickstart](/docs/quickstart), so it can discover and run eligible tools. The examples below continue from the Session above.
112
113
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
114
<Tab value="Python">
115
```python
148
-tools = session.tools() # Pass these to your agent framework.
116
+tools = session.tools()
117
```
118
</Tab>
119
<Tab value="TypeScript">
120
```typescript
121
import { Composio } from "@composio/core";
122
const composio = new Composio();
155
-const session = await composio.create("user_123");
123
+const session = await composio.create("user_123", { toolkits: ["exa"], instant: { returnInstantCharge: true } });
124
// ---cut---
157
-const tools = await session.tools(); // Pass these to your agent framework.
125
+const tools = await session.tools();
126
```
127
</Tab>
128
</Tabs>
@@ -171,14 +139,49 @@ result = session.execute("EXA_SEARCH", arguments={"query": "Composio documentati
139
```typescript
140
import { Composio } from "@composio/core";
141
const composio = new Composio();
174
-const session = await composio.create("user_123");
142
+const session = await composio.create("user_123", { toolkits: ["exa"], instant: { returnInstantCharge: true } });
143
// ---cut---
144
const result = await session.execute("EXA_SEARCH", { query: "Composio documentation" });
145
```
146
</Tab>
147
</Tabs>
148
181
-Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments. A tool appearing in a toolkit does not mean Instant account access is available for that tool. Confirm supported tools and rates during Experimental access.
149
+Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments.
150
+
151
+### Use MCP
152
+
153
+For an MCP client, create the Session with `mcp=True` in Python or `mcp: true` in TypeScript. Pass both the URL and headers to your client. The same Instant policy applies over MCP.
154
+
155
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
156
+<Tab value="Python">
157
+```python
158
+session = composio.sessions.create(
159
+ user_id="user_123",
160
+ toolkits=["exa"],
161
+ instant={"return_instant_charge": True},
162
+ mcp=True,
163
+)
164
+mcp_url = session.mcp.url
165
+mcp_headers = session.mcp.headers
166
+```
167
+</Tab>
168
+<Tab value="TypeScript">
169
+```typescript
170
+import { Composio } from "@composio/core";
171
+const composio = new Composio();
172
+// ---cut---
173
+const session = await composio.create("user_123", {
174
+ toolkits: ["exa"],
175
+ instant: { returnInstantCharge: true },
176
+ mcp: true,
177
+});
178
+const mcpUrl = session.mcp.url;
179
+const mcpHeaders = session.mcp.headers;
180
+```
181
+</Tab>
182
+</Tabs>
183
+
184
+Treat `session.mcp.headers` as a secret. See [Using sessions via MCP](/docs/sessions-via-mcp) for client setup and credential scope.
185
186
### Read charge details
187
@@ -194,7 +197,6 @@ if charge is not None:
197
</Tab>
198
<Tab value="TypeScript">
199
```typescript
197
-// @noErrors
200
import { Composio } from "@composio/core";
201
202
const composio = new Composio();
@@ -209,7 +211,9 @@ console.log(result.instantCharge ?? "No Instant charge");
211
</Tab>
212
</Tabs>
213
212
-The `InstantCharge` type is exported from `composio.types` and includes `amount`, `currency`, and `charged_by`. Python provider integrations and mixed local/remote multi-tool execution also preserve these charge details.
214
+The charge contains `amount`, `currency`, and `charged_by`. `amount` is an exact USD decimal string. Python exports `InstantCharge` from `composio.types`. TypeScript exposes `instantCharge` as `unknown`.
215
+
216
+Connected-account calls do not have an Instant charge. Setting `return_instant_charge` to `false` hides the immediate response charge, but does not prevent billing or remove charges from usage records.
217
218
## Control Instant usage
219
@@ -244,7 +248,6 @@ session = composio.sessions.create(
248
</Tab>
249
<Tab value="TypeScript">
250
```typescript
247
-// @noErrors
251
import { Composio } from "@composio/core";
252
const composio = new Composio();
253
// ---cut---
@@ -276,7 +279,6 @@ session = composio.sessions.create(
279
</Tab>
280
<Tab value="TypeScript">
281
```typescript
279
-// @noErrors
282
import { Composio } from "@composio/core";
283
const composio = new Composio();
284
// ---cut---
@@ -301,7 +303,6 @@ session.update(instant=False)
303
</Tab>
304
<Tab value="TypeScript">
305
```typescript
304
-// @noErrors
306
import { Composio } from "@composio/core";
307
const composio = new Composio();
308
const session = await composio.create("user_123");
@@ -319,16 +320,61 @@ await session.update({ instant: false });
320
321
An Instant account is a provider account held by Composio for specific tools. It is different from **Composio-managed auth**, where Composio supplies OAuth application credentials but your user still connects their own account. Composio-managed auth alone does not make a tool available through Composio Instant.
322
322
-You pay an Instant charge only when Composio's Instant account runs the tool. A call using the user's own connection has no Composio Instant charge; the provider may bill that user under their own plan. If you select a connected account explicitly, that route wins and does not fall back to the Instant account on failure. Otherwise, available user or shared connections take priority over an Instant account. If the chosen tool is not supported by an Instant account, it follows the normal connection flow.
323
+You pay an Instant charge only when Composio's Instant account runs the tool. A call using the user's own connection has no Instant charge. The provider may bill that user under their own plan.
324
+
325
+Without an explicit account selection, Composio prefers the user's own connection, then an available shared connection, then an Instant account. If you select a connected account explicitly, that route wins and does not fall back to Instant on failure. If a tool does not support Instant, it follows the normal connection flow.
326
327
Session search tells you when an Instant account serves a toolkit. The toolkit's connection status includes `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript), which lists the tools that run on it. Any other tool in that toolkit needs the user's own connection.
328
326
-To choose the Instant account explicitly, pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. For direct `composio.tools.execute()`, pass `connected_account_id="instant_account"` in Python or `connectedAccountId: "instant_account"` in TypeScript. This route does not fall back to another credential if it fails.
329
+To choose the Instant account explicitly, pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. The project and Session must permit Instant, and the tool must support it. This route does not fall back to another credential if it fails.
330
+
331
+### Shared-account restrictions and privacy
332
+
333
+Instant accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Actions that expose a shared account's history or other customers' data are excluded. Connect your own provider account when you need account-specific access.
334
+
335
+Tool inputs still go to the provider that runs the tool. Using Instant does not imply zero data retention or replace the provider's data-handling terms. See [Zero data retention](/docs/security/zero-data-retention) for Composio's retention controls.
336
+
337
+## Fund Instant usage
338
+
339
+Instant usage is paid from your organization's balance on every plan, including Enterprise. It is not invoice-funded. Composio adds no markup to provider charges for Instant tools. Other Composio usage remains subject to your plan's pricing.
340
328
-Instant accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `instant` policy.
341
+Check your balance in [Organization Settings → Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). Paid plans can add prepaid funds there. Hobby organizations must upgrade before adding funds.
342
+
343
+When Composio confirms that the balance is exhausted, an Instant call fails with HTTP 402 (`Metering_WalletBalanceExhausted`). It does not fall back to another account. Calls that select a user's connected account can still run. Balance verification is asynchronous, so a zero balance is not a strict per-call spending cap.
344
345
## Review usage
346
332
-Use the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary) for totals and the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution) for individual calls. The summary's `instant_charge` is a top-level field; individual log charges appear in `metadata.instant_charge`. Both are exact USD strings. Filter logs by `session_id` when you need to trace a Session. These records remain available even when `return_instant_charge` is `false`.
347
+Use the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary) for totals. This request returns the authenticated project's last 30 days of usage:
348
+
349
+```bash
350
+curl 'https://backend.composio.dev/api/v3.1/project/usage/summary' \
351
+ --header "x-api-key: $COMPOSIO_API_KEY" \
352
+ --header 'Content-Type: application/json' \
353
+ --data '{}'
354
+```
355
+
356
+Read the top-level `instant_charge` for the total Instant charge as an exact USD string. The separate `entities` object groups metering usage by entity type, with `unit`, `total_quantity`, and `event_count`. Do not treat all billable usage as Instant charges. To choose a window, supply `from` and `to` in Unix epoch milliseconds. `from` is inclusive and `to` is exclusive.
357
+
358
+For individual calls, use the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution). Replace `trs_your_session_id` with your Session ID:
359
+
360
+```bash
361
+curl 'https://backend.composio.dev/api/v3.1/logs/tool_execution' \
362
+ --header "x-api-key: $COMPOSIO_API_KEY" \
363
+ --header 'Content-Type: application/json' \
364
+ --data '{
365
+ "limit": 20,
366
+ "filters": [{"field": "session_id", "operator": "==", "value": "trs_your_session_id"}]
367
+ }'
368
+```
369
+
370
+The response contains `logs` and `next_cursor`. Send `cursor` in the next request to continue. Each log can include `metadata.credential_source` and `metadata.instant_charge`. The source `instant_account` identifies an Instant execution. The charge is an exact USD string, including `"0"` for a recorded zero charge. An absent charge means no charge was recorded, not that the call was free. These records remain available even when `return_instant_charge` is `false`.
371
+
372
+## Troubleshoot access and charges
373
+
374
+- If Instant is unavailable, check the project's **Instant Toolkits** setting, Session filters, and the tool's `instant.supported` field on the latest version.
375
+- If a tool needs a connection, check that individual tool's eligibility. A toolkit badge does not cover every tool.
376
+- If a call has no immediate charge, check `return_instant_charge` and the execution log's `metadata.credential_source`. A personal or shared connection may have taken priority.
377
+- If an Instant call returns HTTP 402, check the organization's balance in Billing.
378
+- Before retrying a failed or timed-out call, check its execution log. A provider may have completed billable work even if your client did not receive the result. Contact [support@composio.dev](mailto:support@composio.dev) with the log ID if the result or charge is unclear.
379
380
See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/api-reference/tool-router/postToolRouterSession) for the complete request schema.