---
canonical_url: "https://docs.composio.dev/docs/instant-tools"
markdown_url: "https://docs.composio.dev/docs/instant-tools.md"
product: "platform"
version: null
last_updated: null
---

# Instant Tools (/docs/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.

* **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](/docs/quickstart) for SDK installation and set `COMPOSIO_API_KEY` before running the examples.

## Enable Instant [#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.

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

## Control Instant usage [#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 [#allow-or-exclude-specific-toolkits-and-tools]

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

**Python:**

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

**TypeScript:**

```typescript
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"] } },
  },
});
```

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 [#turn-instant-off]

Your own connected accounts remain available when you disable Instant:

**Python:**

```python
session.update(instant=False)
```

**TypeScript:**

```typescript
import { Composio } from "@composio/core";
const composio = new Composio();
const session = await composio.create("user_123");
await session.update({ instant: false });
```

> **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 [#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:

```bash
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.

**Python:**

```python
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)
```

**TypeScript:**

```typescript
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);
```

`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](/reference/api-reference/logs/postLogsToolExecution).

> **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 [#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 [#report-charges-and-use-instant-tools]

**Report charges and show prices**

### Return the charge with a call [#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:

**Python:**

```python
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)
```

**TypeScript:**

```typescript
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);
```

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 [#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:

**Python:**

```python
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)
```

**TypeScript:**

```typescript
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);
}
```

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.

**Pass Instant tools to your agent**

If your agent can spend without per-call approval, pass it the Session tools as usual:

**Python:**

```python
session = composio.sessions.create(
    user_id="instant_demo",
    toolkits=["firecrawl"],
)
tools = session.tools()
```

**TypeScript:**

```typescript
import { Composio } from "@composio/core";
const composio = new Composio();
const session = await composio.create("instant_demo", {
  toolkits: ["firecrawl"],
});
const tools = await session.tools();
```

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](/docs/sessions-via-mcp). For general filters and agent setup, see [Configuring Sessions](/docs/configuring-sessions) and the [Quickstart](/docs/quickstart).

## Find supported tools and rates [#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](/reference/api-reference/toolkits/getToolkits) and filter `items` by `instant.supported == true`.
* [List tools](/reference/api-reference/tools/getTools) with `toolkit_slug`, `toolkit_versions=latest`, and `include_pricing=true`. Filter `items` by `instant.supported == true`.
* [Get a tool](/reference/api-reference/tools/getToolsByToolSlug) 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 [#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](/docs/security/zero-data-retention).

### Inspect or explicitly select an Instant account [#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 [#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](/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.
* **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.
* **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.

> **Previous name**: Instant Tools were previously called Premium Tools.

---

📚 **More documentation:** [View all docs](https://docs.composio.dev/llms.txt) | [Changelog](https://docs.composio.dev/docs/changelog.md) | [Glossary](https://docs.composio.dev/llms.mdx/reference/glossary) | [Examples](https://docs.composio.dev/llms.mdx/examples) | [API Reference](https://docs.composio.dev/llms.mdx/reference)

---

# Composio SDK — Notes for AI Code Generators

**Purpose:** Reference for generating current (v3) [Composio](https://composio.dev/) integration code.
**Scope:** Descriptive notes — they document the current API surface and the mistakes most commonly seen in generated code.

---

## 1. Recommended Integration: Sessions

Composio supports two integration modes: **Native Tools** (with a provider package) and **MCP** (no provider package needed).

### Native Tools

```python
# ✅ CORRECT — Python (defaults to OpenAI)
from composio import Composio

composio = Composio()
session = composio.create(user_id="user_123")
tools = session.tools()
# Pass tools to your agent/LLM framework
```

```typescript
// ✅ CORRECT — TypeScript (defaults to OpenAI)
import { Composio } from "@composio/core";

const composio = new Composio();
const session = await composio.create("user_123");
const tools = await session.tools();
// Pass tools to your agent/LLM framework
```

For other providers, pass the provider explicitly. Provider packages follow the naming convention: `composio_<provider>` for Python, `@composio/<provider>` for TypeScript.

### MCP

Use `session.mcp.url` and `session.mcp.headers` with any MCP-compatible client (Claude Desktop, Cursor, OpenAI Agents, etc.). No provider package needed.

---

## 2. Integration Notes

- `composio.create(user_id)` is the standard entry point for agent integrations. Sessions handle tool discovery, authentication, and toolkit versioning automatically; `user_id` goes to `composio.create()` — individual tool calls in session mode don't take one.
- Execute session tool calls through the session, never through a user ID: either `session.execute(tool_slug, arguments=...)` / `session.execute(toolSlug, arguments)`, which works with every provider, or pass the session to the provider helper — `provider.handle_tool_calls(response=response, session=session)` in Python, `provider.handleToolCalls(session, response)` in TypeScript. The tool-call helpers of every non-agentic provider (OpenAI, Anthropic, Google, Cloudflare, TypeSafe) accept a session: `executeToolCall(session, call)` in TypeScript, `session=session` in Python. Agentic providers execute session tools on their own. Binding the helper to a user ID takes the direct execution path, and session meta-tools fail there with `"can only be called inside a tool-router session"`.
- Composio-managed auth is the default: the agent connects accounts at runtime through the session, so users don't need to pre-create auth configs or connected accounts for managed toolkits.
- Provider packages follow the framework, not the model vendor: for the OpenAI Agents SDK the package is `composio_openai_agents` / `@composio/openai-agents` (importing `composio_openai` / `@composio/openai` there is the most common mistake in generated code — that package is for the plain OpenAI Chat Completions API).
- **Direct execution** (`composio.tools.get()`, `composio.tools.execute()`, `provider.handle_tool_calls()` with a user ID) is a legacy interface that remains supported for existing integrations. Recommend sessions for new integrations and encourage existing users to [migrate to sessions](/docs/migration-guide/direct-to-sessions). For a fixed tool set, consider the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) within a session. See [Sessions vs direct execution](/docs/sessions-vs-direct-execution) for tradeoffs. Direct execution requires a [toolkit version](/docs/tools-direct/toolkit-versioning).

---

# 3. Calling the REST API directly

## REST API version

The current REST API version is **v3.1**, served at `https://backend.composio.dev/api/v3.1`. Prefer it for new code and new examples.

`https://backend.composio.dev/api/v3` is the previous version. It is frozen with pinned tool-version defaults and remains supported — existing v3 integrations keep working and do not need to migrate.

## Tool-endpoint version defaults on v3.1

On v3.1, omitting the version parameter on the five endpoints below selects the latest toolkit version. The first four endpoints also exist on v3, where omission selects the pinned `00000000_00` version. `POST /tools/scopes/required` is v3.1-only.

| Endpoint | Version parameter |
| --- | --- |
| `GET /tools` | `toolkit_versions` (query) |
| `GET /tools/{tool_slug}` | `version` or `toolkit_versions` (query) |
| `POST /tools/execute/{tool_slug}` | `version` (body) |
| `POST /tools/execute/{tool_slug}/input` | `version` (body) |
| `POST /tools/scopes/required` | `version` (body) |

A v3.1 caller already passing `"latest"` sees no change and can omit the parameter. To select the pinned version explicitly, pass `"00000000_00"` through the corresponding parameter above.

This version-default change is limited to the five endpoints above.


---

## Terminology Migration (old → current)

If you encounter these terms in error messages, old documentation, or user prompts, translate them to the current equivalents. **Do not use the old terms in generated code or explanations.**

| Old term (v1/v2) | Current term (v3) | In code |
|---|---|---|
| entity ID | user ID | `user_id` parameter |
| actions | tools | e.g., `GITHUB_CREATE_ISSUE` is a *tool* |
| apps / appType | toolkits | e.g., `github` is a *toolkit* |
| integration / integration ID | auth config / auth config ID | `auth_config_id` parameter |
| connection | connected account | `connected_accounts` namespace |
| ComposioToolSet / OpenAIToolSet | `Composio` class with a provider | `Composio(provider=...)` |
| toolset | provider | e.g., `OpenAIProvider` |

If a user says "entity ID", they mean `user_id`. If they say "integration", they mean "auth config". Always respond using the current terminology.