> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Instant Tools

> Give your agent supported tools without asking every user to connect a provider account

Instant Tools run supported actions on Composio's provider accounts and charge your organization's Composio balance. Your users don't need a separate provider account or API key.

* **Set up basic controls:** [Allow or exclude toolkits and tools](#allow-or-exclude-specific-toolkits-and-tools), or [turn Instant off](#turn-instant-off).
* **Want approval before spending?** Keep execution in your application and [ask before each call](#approve-a-tool-call-before-spending).
* **Need a Session spend cap?** There is no built-in dollar cap. Use an [application-side budget](#limit-session-spending), or disable Instant with `instant=False` in Python or `instant: false` in TypeScript.

New to Composio? Follow the [Quickstart](https://composio-preview.mintlify.site/docs/quickstart.md) for SDK installation and set `COMPOSIO_API_KEY` before running the examples.

## Enable Instant

1. Turn on **Instant Toolkits** in [project Settings](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs\&utm_medium=content\&utm_campaign=instant-tools). It's off by default.
2. Check your organization's prepaid balance in [Billing](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs\&utm_medium=content\&utm_campaign=instant-tools).

Once enabled, eligible tools can use Instant in new and existing Sessions unless their Session policy prevents it. Omitting `instant` permits Instant usage; a Session cannot override a project where Instant is off.

> [!NOTE]
>
> **Experimental access**
>
> If the setting is unavailable, contact [support@composio.dev](mailto:support@composio.dev) to request access.

## Control Instant usage

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.

### Allow or exclude specific toolkits and tools

Keep Exa and Firecrawl available, but allow Instant only for `EXA_SEARCH`:

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     toolkits=["exa", "firecrawl"],
>     instant={
>         "toolkits": {"enable": ["exa"]},
>         "tools": {"exa": {"enable": ["EXA_SEARCH"]}},
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
> const composio = new Composio();
> const session = await composio.create("user_123", {
>   toolkits: ["exa", "firecrawl"],
>   instant: {
>     toolkits: { enable: ["exa"] },
>     tools: { exa: { enable: ["EXA_SEARCH"] } },
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["exa", "firecrawl"]},
>     "instant": {
>       "toolkits": {"enable": ["exa"]},
>       "tools": {"exa": {"enable": ["EXA_SEARCH"]}}
>     }
>   }'
> ```

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.

Omitting `instant.toolkits` leaves other eligible toolkits permitted. A `tools.exa` rule alone does not restrict Instant to Exa.

### Turn Instant off

Your own connected accounts remain available when you disable Instant:

> [tab] Python
>
> ```python theme={null}
> session.update(instant=False)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from "@composio/core";
> const composio = new Composio();
> const session = await composio.create("user_123");
> await session.update({ instant: false });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"instant": false}'
> ```

> [!WARNING]
>
> **Updating a disabled Session**
>
> 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.

## Approve a tool call before spending

This human-in-the-loop (HITL) example asks you to approve one Firecrawl scrape before executing it. First, inspect the tool's current published rate:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
> tool = composio.client.get(
>     "/api/v3.1/tools/FIRECRAWL_SCRAPE",
>     cast_to=object,
>     query={"toolkit_versions": "latest", "include_pricing": True},
> )
> print(tool)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const tool = await composio.getClient().get<unknown>('/api/v3.1/tools/FIRECRAWL_SCRAPE', {
>   query: { toolkit_versions: 'latest', include_pricing: true },
> });
> console.log(tool);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -X GET "https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE?toolkit_versions=latest&include_pricing=true" \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   | jq '{slug, instant, input_parameters}'
> ```

Check that `instant.supported` is `true`. Read `instant.price.description` and any `instant.price.discount` before approving. These are strings, not a machine-readable maximum cost; missing pricing does not mean the tool is free.

Then run the example. It shows the exact arguments, waits for `yes`, and makes one tool call. Any other answer exits without creating a Session or executing the tool.

> [tab] Python
>
> ```python theme={null}
> import json
> from composio import Composio
>
> tool = "FIRECRAWL_SCRAPE"
> arguments = {"url": "https://composio.dev"}
>
> print(tool, json.dumps(arguments))
> if input("Approve this call at the published rate? Type yes: ").strip().lower() != "yes":
>     raise SystemExit("Not approved. No tool call made.")
>
> composio = Composio()
> session = composio.sessions.create(
>     user_id="instant_demo",
>     toolkits=["firecrawl"],
>     instant={"return_instant_charge": True},
> )
> result = session.execute(tool, arguments=arguments, account="instant_account")
> print(result)
> print("Instant charge:", result.instant_charge)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { createInterface } from "node:readline/promises";
> import { Composio } from "@composio/core";
>
> const tool = "FIRECRAWL_SCRAPE";
> const args = { url: "https://composio.dev" };
> const prompt = createInterface({ input: process.stdin, output: process.stdout });
>
> console.log(tool, JSON.stringify(args));
> let answer: string;
> try {
>   answer = await prompt.question("Approve this call at the published rate? Type yes: ");
> } finally {
>   prompt.close();
> }
> if (answer.trim().toLowerCase() !== "yes") {
>   throw new Error("Not approved. No tool call made.");
> }
>
> const composio = new Composio();
> const session = await composio.create("instant_demo", {
>   toolkits: ["firecrawl"],
>   instant: { returnInstantCharge: true },
> });
> const result = await session.execute(tool, args, { account: "instant_account" });
> console.log(result);
> console.log("Instant charge:", result.instantCharge);
> ```

> [tab] API
>
> ```bash theme={null}
> echo 'FIRECRAWL_SCRAPE {"url": "https://composio.dev"}'
> read -r -p "Approve this call at the published rate? Type yes: " ANSWER
> if [ "$ANSWER" != "yes" ]; then
>   echo "Not approved. No tool call made."
>   exit 1
> fi
>
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_instant_charge": true}}' \
>   | jq -r '.session_id')
>
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"tool_slug": "FIRECRAWL_SCRAPE", "arguments": {"url": "https://composio.dev"}, "account": "instant_account"}' \
>   | jq '{result_type, data, instant_charge}'
> ```

`account="instant_account"` (Python) or `account: "instant_account"` (TypeScript) explicitly selects Instant rather than your user's provider connection. The response reports the charge when available. To verify billing, check `metadata.credential_source` and `metadata.instant_charge` in the [execution logs](https://composio-preview.mintlify.site/reference/api-reference/logs/postLogsToolExecution.md).

> [!WARNING]
>
> **Keep approval on the execution path**
>
> This prompt protects only this `session.execute()` call. Keep the spending Session and MCP endpoint private to your executor, and require approval for each exact tool and arguments. Passing `session.tools()` or the MCP endpoint directly to an agent bypasses this gate. Agent instructions are not an enforcement boundary.

## Limit Session spending

The Session API does not have a dollar spend-cap parameter. `return_instant_charge` / `returnInstantCharge` reports costs **after** execution; it does not authorize or limit spending. Your prepaid balance is not a hard cap either, because balance checks are asynchronous.

For a per-Session budget, enforce it in the same application-side executor that asks for approval:

1. Store the budget and outstanding reservations by Session ID.
2. Before each call, reserve a trusted upper bound for that call's cost. Reject the call if it would exceed the remaining budget or you cannot establish a bound. Do not parse the published price description as a guaranteed quote.
3. Reserve atomically so concurrent calls cannot spend the same remaining budget. Bind human approval to the tool, arguments, and reserved amount.
4. Reconcile the reservation against the actual charge in the execution log. Keep unresolved reservations after a timeout, failure, or missing charge, and check the log before retrying.

Use exact decimal arithmetic for USD amounts. Reject any call whose maximum cost you cannot bound if you need a strict dollar limit. For the simpler policy “no unapproved paid calls,” use the approval example above. To prevent all Instant spending in a Session, [turn Instant off](#turn-instant-off).

## Report charges and use Instant tools

> [accordion] Report charges and show prices
>
> ### Return the charge with a call
>
> 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:
>
> > [tab] Python
> >
> > ```python theme={null}
> > session = composio.sessions.create(
> >     user_id="instant_demo",
> >     toolkits=["firecrawl"],
> >     instant={"return_instant_charge": True},
> > )
> > result = session.execute("FIRECRAWL_SCRAPE", arguments={"url": "https://composio.dev"})
> > if result.instant_charge is not None:
> >     print(result.instant_charge.amount, result.instant_charge.currency)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from "@composio/core";
> > const composio = new Composio();
> > const session = await composio.create("instant_demo", {
> >   toolkits: ["firecrawl"],
> >   instant: { returnInstantCharge: true },
> > });
> > const result = await session.execute("FIRECRAWL_SCRAPE", { url: "https://composio.dev" });
> > console.log(result.instantCharge);
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_instant_charge": true}}' \
> >   | jq -r '.session_id')
> >
> > curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/execute \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"tool_slug": "FIRECRAWL_SCRAPE", "arguments": {"url": "https://composio.dev"}}' \
> >   | jq '.instant_charge'
> > ```
>
> 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.
>
> ### Show prices in search
>
> To see what an Instant tool costs before you call it, set `return_prices_in_search` in Python or `returnPricesInSearch` in TypeScript. This option is experimental and off by default. Search results then list each Instant tool's published price under the toolkit's Instant account, keyed by tool slug:
>
> > [tab] Python
> >
> > ```python theme={null}
> > session = composio.sessions.create(
> >     user_id="instant_demo",
> >     toolkits=["firecrawl"],
> >     instant={"return_prices_in_search": True},
> > )
> > results = session.search(query="scrape a web page")
> > for status in results.toolkit_connection_statuses:
> >     if status.instant_account is not None:
> >         print(status.toolkit, status.instant_account.prices)
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from "@composio/core";
> > const composio = new Composio();
> > const session = await composio.create("instant_demo", {
> >   toolkits: ["firecrawl"],
> >   instant: { returnPricesInSearch: true },
> > });
> > const results = await session.search({ query: "scrape a web page" });
> > for (const status of results.toolkitConnectionStatuses) {
> >   console.log(status.toolkit, status.instantAccount?.prices);
> > }
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}, "instant": {"return_prices_in_search": true}}' \
> >   | jq -r '.session_id')
> >
> > curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/search \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"queries": [{"use_case": "scrape a web page"}]}' \
> >   | jq '.toolkit_connection_statuses[] | select(.instant_account != null) | {toolkit, prices: .instant_account.prices}'
> > ```
>
> Each price has a `description` and, when one applies, a `discount`. Like charge reporting, this setting only controls what the response shows. It does not turn Instant usage on or off.

> [accordion] Pass Instant tools to your agent
>
> If your agent can spend without per-call approval, pass it the Session tools as usual:
>
> > [tab] Python
> >
> > ```python theme={null}
> > session = composio.sessions.create(
> >     user_id="instant_demo",
> >     toolkits=["firecrawl"],
> > )
> > tools = session.tools()
> > ```
>
> > [tab] TypeScript
> >
> > ```typescript theme={null}
> > import { Composio } from "@composio/core";
> > const composio = new Composio();
> > const session = await composio.create("instant_demo", {
> >   toolkits: ["firecrawl"],
> > });
> > const tools = await session.tools();
> > ```
>
> > [tab] API
> >
> > ```bash theme={null}
> > SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
> >   -H "x-api-key: $COMPOSIO_API_KEY" \
> >   -H "Content-Type: application/json" \
> >   -d '{"user_id": "instant_demo", "toolkits": {"enable": ["firecrawl"]}}' \
> >   | jq -r '.session_id')
> >
> > curl -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/tools \
> >   -H "x-api-key: $COMPOSIO_API_KEY"
> > ```
>
> Ask your agent: “Read [https://composio.dev](https://composio.dev) and summarize what the company offers.” With Instant enabled and no existing Firecrawl connection, it can use a supported tool without asking for a Firecrawl API key.
>
> Instant works with `session.tools()`, `session.execute()`, and the Session's [MCP endpoint](https://composio-preview.mintlify.site/docs/sessions-via-mcp.md). For general filters and agent setup, see [Configuring Sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) and the [Quickstart](https://composio-preview.mintlify.site/docs/quickstart.md).

## Find supported tools and rates

Instant support is **per tool**. A toolkit supporting Instant does not mean every tool in that toolkit supports it.

* [List toolkits](https://composio-preview.mintlify.site/reference/api-reference/toolkits/getToolkits.md) and filter `items` by `instant.supported == true`.
* [List tools](https://composio-preview.mintlify.site/reference/api-reference/tools/getTools.md) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
* [Get a tool](https://composio-preview.mintlify.site/reference/api-reference/tools/getToolsByToolSlug.md) with `include_pricing=true` to check its support, rate, and input schema before executing it.

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.

You can also change price reporting on an existing Session with `session.update(instant={"return_prices_in_search": True})` in Python or `await session.update({ instant: { returnPricesInSearch: true } })` in TypeScript.

## Know which account runs the tool

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.

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.

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](https://composio-preview.mintlify.site/docs/security/zero-data-retention.md).

### Inspect or explicitly select an Instant account

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.

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.

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.

## Balance, usage, and troubleshooting

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.

* **Usage totals:** call the [project usage summary API](https://composio-preview.mintlify.site/reference/api-reference/projects/postProjectUsageSummary.md). 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.
* **Individual calls:** query the [execution logs API](https://composio-preview.mintlify.site/reference/api-reference/logs/postLogsToolExecution.md) with a `session_id` filter. Check `metadata.credential_source` and `metadata.instant_charge`. An absent charge is not proof that the call was free.
* **Instant unavailable:** check the project setting, Session restrictions, and the individual tool's eligibility on the latest version.
* **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.
* **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.

> [!NOTE]
>
> **Previous name**
>
> Instant Tools were previously called Premium Tools.
