--- canonical_url: "https://docs.composio.dev/docs/security/zero-data-retention" markdown_url: "https://docs.composio.dev/docs/security/zero-data-retention.md" product: "platform" version: null last_updated: null --- # Zero Data Retention (/docs/security/zero-data-retention) When Zero Data Retention (ZDR) is on, Composio does not store the payloads of covered calls. It runs each covered tool call and Proxy Execute request and returns the result without writing the request arguments, response data, or error text to its execution logs. The log for each call keeps metadata only, such as IDs, the tool, timing, and the HTTP status code. > ZDR is available on paid plans for a [usage-based price](https://composio.dev/pricing) and included on Enterprise. An organization admin turns it on in **Organization Settings > Billing > Add-ons**. ## How ZDR works [#how-zdr-works] For each covered call, Composio writes a log that holds metadata only: | Data | Fields | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Stored | IDs for the log, project, connected account, auth config, API key, session, sandbox, and request. The user ID you pass. The toolkit, tool, and tool version. The SDK source, runtime, and framework. Timing, the HTTP status code, and whether the call errored. | | Not stored | Request arguments, response data, and error text. | Composio stores the user ID you pass, so use opaque IDs, such as a database key, rather than emails or names. ## Scope [#scope] ZDR applies per project. It covers requests that use a ZDR project's API key, session, or MCP URL. On the Enterprise plan, new projects start with ZDR on, whether you create them in the dashboard or through the API. On other paid plans, new projects start with ZDR off, even when ZDR is on for all projects. Turn it on for each new project in the dashboard. > Projects without ZDR keep storing payloads. Send requests that need ZDR only to projects that have it on. ## What ZDR covers [#what-zdr-covers] In a ZDR project, Composio does not store payloads for: * Tool calls, whether you execute a tool directly or through a session. * [Proxy Execute](/docs/extending-sessions/proxy-execute) requests. **ZDR covers calls through Composio Managed apps only on the Enterprise plan.** ## What ZDR does not cover [#what-zdr-does-not-cover] ZDR does not cover the following, even in a ZDR project. For how long Composio keeps logs, files, and sandbox data, see [Data retention and handling](/docs/security/data-retention). | Feature | Details | What to do | | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Composio Managed apps, except on the Enterprise plan | Auth configs that use Composio's own OAuth app. | Use [your own OAuth app](/docs/authentication/custom-app-vs-managed-app#create-a-custom-auth-config) for toolkits that need ZDR. Existing users reconnect through the new auth config. You can also [contact sales](https://composio.dev/contact?utm_source=docs\&cta_placement=docs-zero-data-retention) about Enterprise. | | Instant Tools | Composio does not store their payloads, but the third-party provider behind each [hosted account](/docs/instant-tools#know-which-account-runs-the-tool) may keep data under its own policy. | Set `instant=False` in Python or `instant: false` in TypeScript when you create Sessions that handle data that needs ZDR. | | Triggers | With ZDR on, trigger logs leave out event payloads, but Composio still stores the events to process and deliver them. | Do not use triggers for data that needs ZDR. | | Sandbox | The sandbox includes the Workbench and remote Bash. Sessions also offload large responses to it. Sessions turn on the sandbox by default. | [Disable the sandbox](#disable-the-sandbox-in-sessions) when you create sessions. | | Files | Composio stages files that tools upload or download, including Proxy Execute binary responses, and cleans them up after 24 hours. | Do not use tools that upload or download files for data that needs ZDR. | | Tool search in sessions | Composio can cache search queries to improve results. | Keep sensitive data out of search queries, or use the [direct tools preset](/docs/configuring-sessions#direct-tools-preset) to turn off tool search. | | Third parties | The destination apps you connect, your model provider, external MCP servers, and your own logs keep their own data policies. | Review each provider's data policy, and set retention for your own logs. | ### Disable the sandbox in sessions [#disable-the-sandbox-in-sessions] Turn off the sandbox when you create a session: **Python:** ```python from composio import Composio composio = Composio() session = composio.sessions.create( user_id="user_123", sandbox={"enable": False}, ) ``` **TypeScript:** ```typescript import { Composio } from '@composio/core'; const composio = new Composio({ apiKey: 'your_api_key' }); const session = await composio.create("user_123", { sandbox: { enable: false }, }); ``` See [Disabling the sandbox](/docs/configuring-sessions#disabling-the-sandbox) for what changes in the session. ## Always stored [#always-stored] Composio stores audit logs and telemetry on every plan, and ZDR does not change them. Neither contains personally identifiable information (PII). * **Audit logs** record who did what and when, including the metadata row for each tool call. * **Telemetry** is the metrics, traces, application logs, error reports, and usage metering that Composio uses to run and bill the service. Telemetry can include error messages returned by providers. ## Existing data [#existing-data] ZDR applies only to new calls. Logs written before you turned it on keep their payloads for up to one year under the [standard retention policy](/docs/security/data-retention#how-long-logs-are-retained). If you turn ZDR off, new calls store payloads again. ## Turn ZDR on or off [#turn-zdr-on-or-off] Only organization admins can turn ZDR on or off. Other members can see its status but cannot change it. 1. In the dashboard, open [**Organization Settings > Billing**](https://dashboard.composio.dev/~/org/settings/billing?utm_source=docs\&utm_medium=content\&utm_campaign=docs-zero-data-retention). 2. Under **Add-ons**, turn on **Zero Data Retention**. 3. Review the price and what ZDR does not cover, then confirm. ZDR turns on for every current project. To turn ZDR on or off for one project, open [**Project Settings > General**](https://dashboard.composio.dev/~/project/settings/general?utm_source=docs\&utm_medium=content\&utm_campaign=docs-zero-data-retention) and use the **Zero Data Retention** setting. To turn it off for every project, turn off **Zero Data Retention** in Billing. ### Hobby plan [#hobby-plan] ZDR is not available on the Hobby plan. Projects that already had **Don't store data** on keep ZDR on, and an admin can turn it off. Turning it back on requires a paid plan. ### Projects that used Don't store data [#projects-that-used-dont-store-data] ZDR replaces the **Don't store data** option under **Log storage**. Projects that had it on now have ZDR on, and the rest have it off. ## Related [#related] * [Data retention and handling](/docs/security/data-retention): the standard retention policy for every plan. * [Token custody architecture](/docs/security/token-custody): where credentials live and how Composio uses them. * [Composio Trust Center](https://trust.composio.dev): compliance reports and the sub-processor list. * [Data Processing Addendum](https://composio.dev/legal/dpa) and [Business Associate Agreement](https://composio.dev/legal/baa). * [Pricing](https://composio.dev/pricing). --- 📚 **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_` for Python, `@composio/` 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.