Instant Tools

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.

• 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=False in Python or instant: false in TypeScript.

New to Composio? Follow the Quickstart for SDK installation and set COMPOSIO_API_KEY before running the examples.

Enable Instant

1. Turn on Instant Toolkits in project Settings. It's off by default.
2. Check your organization's prepaid balance in Billing.

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.

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:

curl --get 'https://backend.composio.dev/api/v3.1/tools/FIRECRAWL_SCRAPE' \
  --header "x-api-key: $COMPOSIO_API_KEY" \
  --data-urlencode 'toolkit_versions=latest' \
  --data-urlencode 'include_pricing=true' \
  | 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.

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)

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:

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.

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.

Turn Instant off

Your own connected accounts remain available when you disable Instant:

session.update(instant=False)

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 items by instant.supported == true.
• List tools with toolkit_slug, toolkit_versions=latest, and include_pricing=true. Filter items by instant.supported == true.
• Get a tool 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.

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 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. If your plan doesn't allow adding funds, upgrade or contact support.

• Usage totals: call the project usage summary API. 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 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 with the log ID if the result or charge is unclear.