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: show Instant eligibility and disable controls
Palash Kala committed
Sep 30, 2026 at 00:51 UTC
bf832883ac20ff32a57c5ddafe7e91376490e5c9
3 files changed
+44
-3
docs/content/docs/instant-tools.mdx
+44
-3
@@ -21,7 +21,13 @@ Developer organizations get a one-time $2 starter credit. Check your balance in
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.
23
24
-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) for the supported tools and rates before allowing them in a production Session.
24
+In the dashboard, open **Toolkits** and select the **Instant Tools** filter. 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." />
29
+
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.
31
32
## Create a Session
33
@@ -64,12 +70,14 @@ Top-level `toolkits` controls which tools the Session can discover and run. Omit
70
71
## Run a search with an agent
72
67
-Install `composio` and `openai-agents`, then set `COMPOSIO_API_KEY` and `OPENAI_API_KEY` as in the [Quickstart](/docs/quickstart). This small agent can choose when to search. The wrapper prints the Instant charge after each search call:
73
+Install `composio`, `openai-agents`, and `python-dotenv`, then 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:
74
75
```python
76
from agents import Agent, Runner, function_tool
77
from composio import Composio
78
+from dotenv import load_dotenv
79
80
+load_dotenv()
81
session = Composio().sessions.create(user_id="user_123", toolkits=["exa"], instant={"return_instant_charge": True})
82
83
@function_tool
@@ -129,7 +137,7 @@ Check the current [tool input schema](/reference/api-reference/tools/getToolsByT
137
138
### Read charge details
139
132
-With `instant.return_instant_charge` enabled, `session.execute()` returns charge details when available in the typed `instant_charge` field on `ToolRouterSessionExecuteResponse`. Read it from the result above:
140
+With `instant.return_instant_charge` enabled, the response from `session.execute()` includes `instant_charge` when an Instant account runs the tool. Read it from the result above:
141
142
```python
143
charge = result.instant_charge
@@ -159,6 +167,7 @@ console.log(result.instantCharge ?? "No Instant charge");
167
`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.
168
169
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.
170
+
171
The examples below use Python and REST field names. In TypeScript, use `instant` and `returnInstantCharge`, and read the charge from `instantCharge` on the tool result.
172
173
| Session value | Effect |
@@ -201,6 +210,38 @@ const session = await composio.create("user_123", {
210
</Tab>
211
</Tabs>
212
213
+To keep both toolkits discoverable but exclude Firecrawl and `EXA_SEARCH` from Instant usage, use `disable`:
214
+
215
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
216
+<Tab value="Python">
217
+```python
218
+session = composio.sessions.create(
219
+ user_id="user_123",
220
+ toolkits=["exa", "firecrawl"],
221
+ instant={
222
+ "toolkits": {"disable": ["firecrawl"]},
223
+ "tools": {"exa": {"disable": ["EXA_SEARCH"]}},
224
+ },
225
+)
226
+```
227
+</Tab>
228
+<Tab value="TypeScript">
229
+```typescript
230
+// @noErrors
231
+import { Composio } from "@composio/core";
232
+const composio = new Composio();
233
+// ---cut---
234
+const session = await composio.create("user_123", {
235
+ toolkits: ["exa", "firecrawl"],
236
+ instant: {
237
+ toolkits: { disable: ["firecrawl"] },
238
+ tools: { exa: { disable: ["EXA_SEARCH"] } },
239
+ },
240
+});
241
+```
242
+</Tab>
243
+</Tabs>
244
+
245
To stop Instant usage on an existing Session, update its policy:
246
247
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
docs/public/images/instant-tool-eligibility.png
Binary files /dev/null and b/docs/public/images/instant-tool-eligibility.png differ
docs/public/images/instant-toolkit-filter.png
Binary files /dev/null and b/docs/public/images/instant-toolkit-filter.png differ