Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 11:00 UTC
docs: clarify experimental billing defaults and v3.1 links
Palash Kala committed
Sep 23, 2026 at 17:34 UTC
b79bb67b76dd48335420ae0de7f44301fd44e792
1 file changed
+10
-6
docs/content/docs/instant-tools.mdx
+10
-6
@@ -1,15 +1,17 @@
1
---
2
-title: Instant Tools
2
+title: Instant Tools (Experimental)
3
description: Use supported tools in a Session without asking every user to connect a provider account
4
keywords: [Instant Tools, Sessions, premium usage, Composio-managed account]
5
---
6
7
-Instant Tools let your Session run supported tools without an end-user provider connection. Composio supplies the provider account and charges eligible calls to your project's Composio balance.
7
+Instant Tools let your Session run supported tools without an end-user provider connection. For these tools, a Composio-managed account supplies the provider access and eligible calls incur a `premium_usage` charge against your organization's Composio balance.
8
9
<Callout type="warning" title="Experimental access">
10
This feature requires a project setting that is not yet self-service. Email [support@composio.dev](mailto:support@composio.dev) to enable it for your project and confirm which tools and rates are available. Session configuration cannot override a project where the setting is off.
11
</Callout>
12
13
+Once the project setting is enabled, new Sessions can use eligible billed tools by default, even if `premium_usage` is omitted. Send `"premium_usage": false` on Session creation if that Session must not use Composio-billed access.
14
+
15
## Create a Session
16
17
After your project is enabled, create a Session with an explicit `premium_usage` policy. This example makes Exa available to the Session and permits Composio-billed access for Exa:
@@ -35,7 +37,7 @@ The two toolkit lists control different things. Top-level `toolkits` controls wh
37
38
## Find and run a tool
39
38
-You can inspect a tool's input schema with the [get tool endpoint](/reference/v3/api-reference/tools/getToolsByToolSlug). For example:
40
+You can inspect a tool's input schema with the [get tool endpoint](/reference/api-reference/tools/getToolsByToolSlug). For example:
41
42
```bash
43
curl --request GET \
@@ -43,7 +45,7 @@ curl --request GET \
45
--header "x-api-key: $COMPOSIO_API_KEY"
46
```
47
46
-Then execute a tool through the Session using the [Session execute endpoint](/reference/v3/api-reference/tool-router/postToolRouterSessionBySessionIdExecute):
48
+Then execute a tool through the Session using the [Session execute endpoint](/reference/api-reference/tool-router/postToolRouterSessionBySessionIdExecute):
49
50
```bash
51
curl --request POST \
@@ -62,6 +64,8 @@ Check the current tool schema before constructing `arguments`; fields can change
64
65
`premium_usage` is a Session policy. It does not enable a toolkit that top-level `toolkits` excludes, and it does not change a connected account you explicitly selected.
66
67
+The toolkit filter and per-tool filter intersect. A `tools.exa` rule alone does not disable billed access for other eligible toolkits. Use `premium_usage.toolkits` when you need a toolkit allowlist. Each filter accepts either `enable` or `disable`, not both.
68
+
69
| Session value | Effect |
70
|---|---|
71
| Omitted or `{}` | Permits eligible Composio-billed tools, subject to the project setting and normal Session filters. The charge is not returned in tool responses by default. |
@@ -83,7 +87,7 @@ For example, keep Exa and Firecrawl available, but permit billed access only for
87
}
88
```
89
86
-To stop Composio-billed access on an existing Session, use the [Session patch endpoint](/reference/v3/api-reference/tool-router/patchToolRouterSessionBySessionId):
90
+To stop Composio-billed access on an existing Session, use the [Session patch endpoint](/reference/api-reference/tool-router/patchToolRouterSessionBySessionId):
91
92
```bash
93
curl --request PATCH \
@@ -103,4 +107,4 @@ If you select a connected account explicitly, that route wins and does not fall
107
108
Composio-managed accounts cannot run arbitrary provider requests through proxy execution. Use supported tool actions. Direct execution outside a Session does not inherit its `premium_usage` policy.
109
106
-See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/v3/api-reference/tool-router/postToolRouterSession) for the complete request schema.
110
+See [Configuring Sessions](/docs/configuring-sessions) for general toolkit and tool filters and the [create Session API reference](/reference/api-reference/tool-router/postToolRouterSession) for the complete request schema.