Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: focus Instant guide on motivation and feature-specific setup
palash-c committed
Oct 8, 2026 at 16:09 UTC
249de378e84ce0393b02cdf51f8b27c432f16002
1 file changed
+64
-320
docs/content/docs/instant-tools.mdx
+64
-320
@@ -1,151 +1,29 @@
1
---
2
title: Instant Tools
3
-description: Use supported tools in a Session without asking every user to connect a provider account
3
+description: Give your agent supported tools 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
-You can build an agent that enriches company records or creates media, but asking every user to sign up for another provider and supply an API key interrupts that workflow. Instant Tools run supported actions on Composio's provider accounts without that setup. Users still connect their own accounts when a task needs their identity or private data.
8
+Adding enrichment, scraping, or media creation to your agent shouldn't mean asking every user to sign up for another provider, manage an API key, or buy a separate subscription. Instant tools run supported actions on Composio's provider accounts and charge your organization's Composio balance. Your users still connect their own accounts when a task needs their identity or private data.
9
10
-Already using Sessions? Enable Instant for your project below. Your existing `session.tools()` or MCP integration can then use supported tools, subject to its Session restrictions.
10
+Instant works through [Sessions](/docs/how-composio-works). New to Composio? Follow the [Quickstart](/docs/quickstart) for SDK and agent setup, then return here.
11
12
-## Enable Instant for your project
12
+## Enable Instant
13
14
-Get your `COMPOSIO_API_KEY` from [API keys](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). Use the project's key for the examples below.
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**. Check that your organization has an available balance in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools) before running a tool.
15
16
-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.
17
-
18
-<details>
19
-<summary>Where to enable Instant</summary>
20
-
21
-<Figure src="/images/instant-project-setting.jpg" alt="Instant Toolkits toggle in developer project settings, with a note that calls charge the organization's balance" caption="Enable Instant Toolkits for all Sessions in the project." />
22
-
23
-</details>
24
-
25
-Calls through Instant accounts spend your organization's Composio balance. Once enabled, all Sessions in the project can use eligible Instant tools by default, including existing Sessions, even if `instant` is omitted. Session restrictions still apply. Set `instant=False` in Python or `instant: false` in TypeScript for a Session that must not incur Instant usage charges.
16
+- **Project default:** off. A Session cannot override a project where Instant is off.
17
+- **Once enabled:** eligible tools can use Instant in all Sessions, including existing Sessions. Existing Session restrictions still apply.
18
+- **Session default:** omitting `instant` permits Instant usage. Set `instant=False` in Python or `instant: false` in TypeScript to prevent Instant charges for that Session.
19
20
<Callout type="info" title="Experimental access">
28
- If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
21
+If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.
22
</Callout>
23
31
-Before running the example, check your balance in [Organization Settings → Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). You need available funds for Instant calls. See [funding](#fund-instant-usage) if you need to add funds.
32
-
33
-## Build with Session tools
34
-
35
-This uses the [Quickstart's OpenAI Agents integration](/docs/quickstart). Use Python 3.10 or newer, or Node.js 22.22.3 or newer with ESM imports.
36
-
37
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
38
-<Tab value="Python">
39
-<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
40
-</Tab>
41
-<Tab value="TypeScript">
42
-<PackageInstall packages="dotenv tsx @composio/core @composio/openai-agents @openai/agents" />
43
-</Tab>
44
-</Tabs>
45
-
46
-Create a `.env` file with your keys:
24
+## Use Instant in your agent
25
48
-```dotenv
49
-COMPOSIO_API_KEY=your_composio_project_key
50
-OPENAI_API_KEY=your_openai_key
51
-```
52
-
53
-The OpenAI key runs the model. Instant supplies the Firecrawl credentials for the tool. Both the model and tool calls can incur charges.
54
-
55
-Use a test user ID without existing Firecrawl connections so a personal connection does not take priority. This example asks the agent to extract public company information without asking the user for a Firecrawl account.
56
-
57
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
58
-<Tab value="Python">
59
-```python title="instant_agent.py"
60
-from dotenv import load_dotenv
61
-from composio import Composio
62
-from composio_openai_agents import OpenAIAgentsProvider
63
-from agents import Agent, Runner
64
-
65
-load_dotenv()
66
-composio = Composio(provider=OpenAIAgentsProvider())
67
-session = composio.sessions.create(
68
- user_id="instant_demo",
69
- toolkits=["firecrawl"],
70
- instant={"return_instant_charge": True},
71
-)
72
-agent = Agent(
73
- name="Company researcher",
74
- model="gpt-5.2",
75
- instructions="Use an eligible Instant tool to read the page. Do not invent results.",
76
- tools=session.tools(),
77
-)
78
-result = Runner.run_sync(
79
- agent,
80
- "Read https://composio.dev and summarize what the company offers.",
81
-)
82
-print(result.final_output)
83
-print("Session:", session.session_id)
84
-```
85
-</Tab>
86
-<Tab value="TypeScript">
87
-```typescript title="instant_agent.ts"
88
-import "dotenv/config";
89
-import { Composio } from "@composio/core";
90
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
91
-import { Agent, run } from "@openai/agents";
92
-
93
-const composio = new Composio({ provider: new OpenAIAgentsProvider() });
94
-const session = await composio.create("instant_demo", {
95
- toolkits: ["firecrawl"],
96
- instant: { returnInstantCharge: true },
97
-});
98
-const agent = new Agent({
99
- name: "Company researcher",
100
- model: "gpt-5.2",
101
- instructions: "Use an eligible Instant tool to read the page. Do not invent results.",
102
- tools: await session.tools(),
103
-});
104
-const result = await run(
105
- agent,
106
- "Read https://composio.dev and summarize what the company offers.",
107
-);
108
-console.log(result.finalOutput);
109
-console.log("Session:", session.sessionId);
110
-```
111
-</Tab>
112
-</Tabs>
113
-
114
-Run `python instant_agent.py` or `npx tsx --env-file=.env instant_agent.ts`. The agent should discover a supported Firecrawl tool, read the page, and return a company summary without a Connect Link.
115
-
116
-### Check the result and charge
117
-
118
-The example prints the summary and Session ID. To confirm that Instant handled the call, inspect that Session's logs. Look for `metadata.credential_source: "instant_account"` and `metadata.instant_charge` on the provider tool's execution record. A summary alone does not prove Instant ran the tool.
119
-
120
-<details>
121
-<summary>Fetch the execution logs</summary>
122
-
123
-Use the [tool-execution logs API](/reference/api-reference/logs/postLogsToolExecution). Replace `trs_your_session_id` with your Session ID:
124
-
125
-```bash
126
-curl 'https://backend.composio.dev/api/v3.1/logs/tool_execution' \
127
- --header "x-api-key: $COMPOSIO_API_KEY" \
128
- --header 'Content-Type: application/json' \
129
- --data '{
130
- "limit": 20,
131
- "filters": [{"field": "session_id", "operator": "==", "value": "trs_your_session_id"}]
132
- }'
133
-```
134
-
135
-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`.
136
-
137
-</details>
138
-
139
-`session.tools()` supplies the agent's discovery and execution tools. For another framework, use the matching [provider adapter](/docs/providers). Reuse the Session for later turns as shown in the [Quickstart](/docs/quickstart).
140
-
141
-Top-level `toolkits` controls what the Session can discover and run. Omit it to make all toolkits discoverable. The separate `instant` policy controls Instant usage, as shown under [usage controls](#control-instant-usage).
142
-
143
-<details>
144
-<summary>Call a tool directly with session.execute()</summary>
145
-
146
-### Execute a known tool
147
-
148
-To call a known tool without an agent, use the Session's `execute` method. These examples read the same public page with Firecrawl:
26
+Keep your existing Composio client and agent integration. For example, create a Session with Firecrawl available and pass its tools to your agent as usual:
27
28
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
29
<Tab value="Python">
@@ -153,9 +31,8 @@ To call a known tool without an agent, use the Session's `execute` method. These
31
session = composio.sessions.create(
32
user_id="instant_demo",
33
toolkits=["firecrawl"],
156
- instant={"return_instant_charge": True},
34
)
158
-result = session.execute("FIRECRAWL_SCRAPE", arguments={"url": "https://composio.dev"})
35
+tools = session.tools()
36
```
37
</Tab>
38
<Tab value="TypeScript">
@@ -165,122 +42,47 @@ const composio = new Composio();
42
// ---cut---
43
const session = await composio.create("instant_demo", {
44
toolkits: ["firecrawl"],
168
- instant: { returnInstantCharge: true },
45
});
170
-const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
46
+const tools = await session.tools();
47
```
48
</Tab>
49
</Tabs>
50
175
-Check the current [tool input schema](/reference/api-reference/tools/getToolsByToolSlug) before constructing arguments.
176
-
177
-</details>
178
-
179
-<details>
180
-<summary>Use an MCP client instead</summary>
181
-
182
-### Use MCP
183
-
184
-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.
185
-
186
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
187
-<Tab value="Python">
188
-```python
189
-session = composio.sessions.create(
190
- user_id="user_123",
191
- toolkits=["firecrawl"],
192
- instant={"return_instant_charge": True},
193
- mcp=True,
194
-)
195
-mcp_url = session.mcp.url
196
-mcp_headers = session.mcp.headers
197
-```
198
-</Tab>
199
-<Tab value="TypeScript">
200
-```typescript
201
-import { Composio } from "@composio/core";
202
-const composio = new Composio();
203
-// ---cut---
204
-const session = await composio.create("user_123", {
205
- toolkits: ["firecrawl"],
206
- instant: { returnInstantCharge: true },
207
- mcp: true,
208
-});
209
-const mcpUrl = session.mcp.url;
210
-const mcpHeaders = session.mcp.headers;
211
-```
212
-</Tab>
213
-</Tabs>
51
+Ask your agent: “Read https://composio.dev and summarize what the company offers.” With Instant enabled and no existing Firecrawl connection, the agent can use a supported tool without asking you for a Firecrawl API key.
52
215
-Treat `session.mcp.headers` as a secret. See [Using sessions via MCP](/docs/sessions-via-mcp) for client setup and credential scope.
53
+You don't need a separate Instant execution method. It works with `session.tools()`, `session.execute()`, and the Session's [MCP endpoint](/docs/sessions-via-mcp). For general toolkit filters and agent setup, see [Configuring Sessions](/docs/configuring-sessions) and the [Quickstart](/docs/quickstart).
54
217
-</details>
55
+To verify the call, find the Session's tool execution in the [logs API](/reference/api-reference/logs/postLogsToolExecution). `metadata.credential_source` should be `instant_account`; `metadata.instant_charge` records the charge. An agent's summary alone doesn't prove the tool ran through Instant.
56
57
## Find supported tools and rates
58
221
-Instant coverage is per tool, not per toolkit. A toolkit badge means at least one tool supports Instant. Use a connected account for actions Instant does not support. See [shared-account restrictions](#shared-account-restrictions-and-privacy).
222
-
223
-In the dashboard, open **Toolkits** and select **Instant Toolkits**. A lightning icon marks toolkits with Instant support. Open a toolkit's **Instant tools** tab to see its eligible tools.
224
-
225
-<Figure src="/images/instant-toolkit-filter.jpg" alt="Developer toolkit catalog with the Instant Toolkits filter selected and lightning icons beside eligible toolkits" caption="Filter the toolkit catalog to find Instant support." />
226
-
227
-<Figure src="/images/instant-tool-eligibility.jpg" alt="Firecrawl's Instant tools tab lists Map multiple URLs, Scrape URL, and Search separately from its 29 total tools" caption="Open the Instant tools tab to see which tools support an Instant account." />
59
+Instant support is **per tool**. A toolkit supporting Instant does not mean every tool in that toolkit supports it.
60
229
-<details>
230
-<summary>Discover supported tools and rates through the APIs</summary>
231
-
232
-### List supported toolkits
61
+- [List toolkits](/reference/api-reference/toolkits/getToolkits) and filter `items` by `instant.supported == true` to find toolkits with Instant tools.
62
+- [List tools](/reference/api-reference/tools/getTools) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
63
+- [Get a tool](/reference/api-reference/tools/getToolsByToolSlug) with `include_pricing=true` to check its support, rate, and input schema before executing it.
64
234
-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:
65
+For example, check Firecrawl's scrape tool:
66
67
```bash
237
-curl --get 'https://backend.composio.dev/api/v3.1/toolkits' \
238
- --header "x-api-key: $COMPOSIO_API_KEY" \
239
- --data-urlencode 'limit=100' \
240
- | jq '{items: [.items[] | select(.instant.supported == true)], next_cursor}'
241
-```
242
-
243
-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.
244
-
245
-Do not infer Instant support from `no_auth` or `composio_managed_auth_schemes`. They describe different access routes.
246
-
247
-### Check tool eligibility and rates
248
-
249
-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:
250
-
251
-```bash
252
-curl --get 'https://backend.composio.dev/api/v3.1/tools' \
253
- --header "x-api-key: $COMPOSIO_API_KEY" \
254
- --data-urlencode 'toolkit_slug=exa' \
255
- --data-urlencode 'toolkit_versions=latest' \
256
- --data-urlencode 'include_pricing=true' \
257
- --data-urlencode 'limit=100' \
258
- | jq '{items: [.items[] | select(.instant.supported == true) | {slug, instant}], next_cursor}'
259
-
260
-curl --get 'https://backend.composio.dev/api/v3.1/tools/EXA_SEARCH' \
68
+curl --get 'https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE' \
69
--header "x-api-key: $COMPOSIO_API_KEY" \
70
--data-urlencode 'toolkit_versions=latest' \
71
--data-urlencode 'include_pricing=true' \
72
| jq '{slug, instant, input_parameters}'
73
```
74
267
-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.
75
+Read the rate from `instant.price.description` and any discount from `instant.price.discount`. Both are strings when present; `discount` can be null. Missing pricing does not mean the tool is free.
76
269
-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.
270
-
271
-</details>
77
+Follow `next_cursor` when listing tools or toolkits, including pages with no Instant matches. Instant metadata is absent for older toolkit versions and ineligible tools. Neither `no_auth` nor `composio_managed_auth_schemes` indicates Instant support.
78
79
## Control Instant usage
80
275
-`instant` is a Session policy in both SDKs. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
276
-
277
-The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable Instant usage for other eligible toolkits. Use `instant.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
81
+The Session's top-level `toolkits` filter controls which toolkits your agent can use. The separate `instant` setting controls whether it can use Composio's Instant accounts for those tools.
82
279
-### Disable Instant usage
83
+### Turn Instant off
84
281
-Set `instant=False` in Python or `instant: false` in TypeScript when creating a Session to prevent Instant charges. Your own connected-account routes remain available.
282
-
283
-To stop Instant usage on an existing Session, update its policy:
85
+Your own connected accounts remain available when you disable Instant:
86
87
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
88
<Tab value="Python">
@@ -300,17 +102,13 @@ await session.update({ instant: false });
102
</Tabs>
103
104
<Callout type="warning" title="Updating a disabled Session">
303
- On patch, omitted `instant` fields keep their existing values. But supplying any `instant` object after `instant=false`, even `{ "return_instant_charge": true }`, silently re-enables Instant spending for that Session if the project allows it. Leave `instant` as `false` if the Session must not spend.
105
+Passing any `instant` object after `instant=false` re-enables Instant usage if the project allows it, even if you only set charge reporting. Keep `instant` as `false` when the Session must not spend. Omitting `instant` from an update preserves the existing policy.
106
</Callout>
107
108
<details>
307
-<summary>Restrict Instant to selected toolkits or tools</summary>
308
-
309
-### Restrict toolkits or tools
310
-
311
-Omitted `instant` or `instant={}` permits eligible tools, subject to the project setting and normal Session filters. Omitting `instant.toolkits` does not restrict Instant usage.
109
+<summary>Allow or exclude specific toolkits and tools</summary>
110
313
-For example, keep Exa and Firecrawl available, but permit Instant usage only for `EXA_SEARCH`:
111
+Keep Exa and Firecrawl available, but allow Instant only for `EXA_SEARCH`:
112
113
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
114
<Tab value="Python">
@@ -341,129 +139,75 @@ const session = await composio.create("user_123", {
139
</Tab>
140
</Tabs>
141
344
-To keep both toolkits discoverable but exclude Firecrawl and `EXA_SEARCH` from Instant usage, use `disable`:
345
-
346
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
347
-<Tab value="Python">
348
-```python
349
-session = composio.sessions.create(
350
- user_id="user_123",
351
- toolkits=["exa", "firecrawl"],
352
- instant={
353
- "toolkits": {"disable": ["firecrawl"]},
354
- "tools": {"exa": {"disable": ["EXA_SEARCH"]}},
355
- },
356
-)
357
-```
358
-</Tab>
359
-<Tab value="TypeScript">
360
-```typescript
361
-import { Composio } from "@composio/core";
362
-const composio = new Composio();
363
-// ---cut---
364
-const session = await composio.create("user_123", {
365
- toolkits: ["exa", "firecrawl"],
366
- instant: {
367
- toolkits: { disable: ["firecrawl"] },
368
- tools: { exa: { disable: ["EXA_SEARCH"] } },
369
- },
370
-});
371
-```
372
-</Tab>
373
-</Tabs>
374
-
142
+Use `disable` instead of `enable` to exclude the listed toolkits or tools. Each filter accepts one or the other, not both. Toolkit and tool filters intersect; they cannot enable anything excluded by the Session's top-level filters.
143
144
+Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.
145
146
</details>
147
379
-<details>
380
-<summary>Read charges from a session.execute() response</summary>
381
-
382
-### Inspect charges
148
+### Return the charge with a call
149
384
-With `instant.return_instant_charge` enabled (`instant.returnInstantCharge` in TypeScript), the response from `session.execute()` includes `instant_charge` (`instantCharge` in TypeScript) when an Instant account runs the tool. For the `session.execute()` example above, read it from the result:
150
+Charge reporting is off by default. To include the charge in a `session.execute()` response, set `return_instant_charge` in Python or `returnInstantCharge` in TypeScript:
151
152
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
153
<Tab value="Python">
154
```python
389
-charge = result.instant_charge
390
-if charge is not None:
391
- print(charge.amount, charge.currency, charge.charged_by)
155
+session = composio.sessions.create(
156
+ user_id="instant_demo",
157
+ toolkits=["firecrawl"],
158
+ instant={"return_instant_charge": True},
159
+)
160
+result = session.execute("FIRECRAWL_SCRAPE", arguments={"url": "https://composio.dev"})
161
+if result.instant_charge is not None:
162
+ print(result.instant_charge.amount, result.instant_charge.currency)
163
```
164
</Tab>
165
<Tab value="TypeScript">
166
```typescript
167
import { Composio } from "@composio/core";
397
-
168
const composio = new Composio();
399
-const session = await composio.create("user_123", {
169
+// ---cut---
170
+const session = await composio.create("instant_demo", {
171
toolkits: ["firecrawl"],
172
instant: { returnInstantCharge: true },
173
});
174
const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
404
-// ---cut---
405
-console.log(result.instantCharge ?? "No Instant charge");
175
+console.log(result.instantCharge);
176
```
177
</Tab>
178
</Tabs>
179
410
-The charge contains `amount`, `currency`, and `charged_by`. `amount` is an exact USD decimal string. Python Session execution returns a charge object with these attributes. Python provider integrations and mixed local/remote multi-tool execution preserve the charge as a dictionary typed by `InstantCharge` from `composio.types`. TypeScript exposes `instantCharge` as `unknown`.
411
-
412
-`return_instant_charge` defaults to `false`. 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.
413
-
414
-</details>
415
-
416
-## Know which account runs the tool
417
-
418
-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.
419
-
420
-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.
421
-
422
-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.
180
+The charge includes `amount`, `currency`, and `charged_by`. The amount is an exact USD decimal string. TypeScript exposes `instantCharge` as `unknown`. Turning charge reporting off does not stop billing or remove charges from logs and usage records.
181
424
-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.
182
+## Account selection and privacy
183
426
-You can choose the Instant account explicitly on any project. Pass `account="instant_account"` to Python `session.execute()` or `{ account: "instant_account" }` as TypeScript execution options. On a single-account project, it must match an active connection for that toolkit in the Session. 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.
184
+Composio uses your user's connection first, then an available shared connection, then an Instant account. Only calls through an Instant account incur an Instant charge. Your provider may separately bill calls made with your own account.
185
428
-### Shared-account restrictions and privacy
186
+An explicitly selected account takes priority. A failed connected-account call does not fall back to Instant. Tools that don't support Instant use the normal connection flow.
187
430
-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.
188
+Instant uses shared provider accounts, so tools exposing account history or other customers' data are excluded. Arbitrary proxy requests are not supported. Connect your own account for private data or account-specific actions. Inputs still go to the provider; Instant does not imply [zero data retention](/docs/security/zero-data-retention).
189
432
-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.
433
-
434
-## Fund Instant usage
435
-
436
-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.
437
-
438
-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.
439
-
440
-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.
441
-
442
-## Review usage
190
+<details>
191
+<summary>Inspect or explicitly select an Instant account</summary>
192
444
-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:
193
+Session search returns `instant_account.allowed_tool_slugs` (`instantAccount.allowedToolSlugs` in TypeScript) for a toolkit served by an Instant account. Other tools in that toolkit need your own connection.
194
446
-```bash
447
-curl 'https://backend.composio.dev/api/v3.1/project/usage/summary' \
448
- --header "x-api-key: $COMPOSIO_API_KEY" \
449
- --header 'Content-Type: application/json' \
450
- --data '{}'
451
-```
195
+To select Instant explicitly, pass `account="instant_account"` to Python `session.execute()`, or `{ account: "instant_account" }` as TypeScript execution options. On a single-account project, this must match an active connection for the toolkit in the Session. Project policy, Session policy, and tool eligibility still apply. A failed call does not fall back to another account.
196
453
-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.
197
+Composio-managed auth is different: Composio supplies the OAuth app credentials, but your user still connects their own account. It does not establish Instant support.
198
455
-For individual calls, [inspect the Session's execution logs](#check-the-result-and-charge). These records remain available even when `return_instant_charge` is `false`.
199
+</details>
200
457
-## Troubleshoot access and charges
201
+## Balance, usage, and troubleshooting
202
459
-- If Instant is unavailable, check the project's **Instant Toolkits** setting, Session filters, and the tool's `instant.supported` field on the latest version.
460
-- If a tool needs a connection, check that individual tool's eligibility. A toolkit badge does not cover every tool.
461
-- 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.
462
-- If an Instant call returns HTTP 402, check the organization's balance in Billing.
463
-- 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.
203
+Instant calls use your organization's prepaid balance, including on Enterprise. Check or add funds in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs&utm_medium=content&utm_campaign=instant-tools). If your plan doesn't allow adding funds, upgrade or contact support.
204
465
-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.
205
+- **Usage totals:** call the [project usage summary API](/reference/api-reference/projects/postProjectUsageSummary). Its top-level `instant_charge` is the total Instant charge as a USD string. An empty request body selects the last 30 days; use `from` and `to` in Unix milliseconds for another window.
206
+- **Individual calls:** query the [execution logs API](/reference/api-reference/logs/postLogsToolExecution) with a `session_id` filter. Check `metadata.credential_source` and `metadata.instant_charge`. An absent charge is not proof that the call was free.
207
+- **Instant unavailable:** check the project setting, Session restrictions, and the individual tool's eligibility on the latest version.
208
+- **Balance exhausted:** Instant calls fail with HTTP 402 (`Metering_WalletBalanceExhausted`) once detected, without falling back to another account. Balance checks are asynchronous, not a strict spending cap. Calls using your own connected account can still run.
209
+- **Failed or timed-out call:** check the execution log before retrying. The provider may have completed billable work. Contact [support@composio.dev](mailto:support@composio.dev) with the log ID if the result or charge is unclear.
210
211
<Callout type="info" title="Previous name">
468
- Instant Tools were previously called Premium Tools.
212
+Instant Tools were previously called Premium Tools.
213
</Callout>