- Set up basic controls: Allow or exclude toolkits and tools, or turn Instant off.
- Want approval before spending? Keep execution in your application and ask before each call.
- Need a Session spend cap? There is no built-in dollar cap. Use an application-side budget, or disable Instant with
instant=Falsein Python orinstant: falsein TypeScript.
COMPOSIO_API_KEY before running the examples.
Enable Instant
- Turn on Instant Toolkits in project Settings. It’s off by default.
- Check your organization’s prepaid balance in Billing.
instant permits Instant usage; a Session cannot override a project where Instant is off.
Experimental accessIf the setting is unavailable, contact support@composio.dev to request access.
Control Instant usage
The Session’s top-leveltoolkits 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 forEXA_SEARCH:
- Python
- TypeScript
- API
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:- Python
- TypeScript
- API
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:- Python
- TypeScript
- API
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.
- Python
- TypeScript
- API
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.
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:
- Store the budget and outstanding reservations by Session ID.
- 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.
- Reserve atomically so concurrent calls cannot spend the same remaining budget. Bind human approval to the tool, arguments, and reserved amount.
- 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.
Report charges and use Instant tools
Report charges and show prices
Report charges and show prices
Return the charge with a call
Charge reporting is off by default. To include the charge in asession.execute() response, set return_instant_charge in Python or returnInstantCharge in TypeScript:- Python
- TypeScript
- API
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, setreturn_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:- Python
- TypeScript
- API
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.Pass Instant tools to your agent
Pass Instant tools to your agent
If your agent can spend without per-call approval, pass it the Session tools as usual:Ask your agent: “Read 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
- Python
- TypeScript
- API
session.tools(), session.execute(), and the Session’s MCP endpoint. For general filters and agent setup, see Configuring Sessions and the Quickstart.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 and filter
itemsbyinstant.supported == true. - List tools with
toolkit_slug,toolkit_versions=latest, andinclude_pricing=true. Filteritemsbyinstant.supported == true. - Get a tool with
include_pricing=trueto check its support, rate, and input schema before executing it.
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.Inspect or explicitly select an Instant account
Session search returnsinstant_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. If your plan doesn’t allow adding funds, upgrade or contact support.- Usage totals: call the project usage summary API. Its top-level
instant_chargeis the total Instant charge as a USD string. An empty request body selects the last 30 days; usefromandtoin Unix milliseconds for another window. - Individual calls: query the execution logs API with a
session_idfilter. Checkmetadata.credential_sourceandmetadata.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 with the log ID if the result or charge is unclear.
Previous nameInstant Tools were previously called Premium Tools.