# Execute tool

**Documentation:** /reference/api-reference/tools/postV3_1ToolsExecuteByToolSlug

Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.

---

## POST `/api/v3.1/tools/execute/{tool_slug}`

**Endpoint:** `https://backend.composio.dev/api/v3.1/tools/execute/{tool_slug}`

**Summary:** Execute tool

Execute a specific tool operation with provided arguments and authentication. This is the primary endpoint for integrating with third-party services and executing tools. You can provide structured arguments or use natural language processing by providing a text description of what you want to accomplish.

### Authentication

**ApiKeyAuth** - API Key in `header` header `x-api-key` OR **UserApiKeyAuth** - API Key in `header` header `x-user-api-key`

### Path Parameters

- `tool_slug` (string) *(required)*: The tool slug to execute

### Request Body

**Schema:**

- `connected_account_id` (string): Unique identifier for the connected account to use for authentication
- `entity_id` (string): Deprecated: please use user_id instead. Entity identifier for multi-entity connected accounts (e.g. multiple repositories, organizations)
- `user_id` (string): User id for multi-user connected accounts (e.g. multiple users, organizations)
- `version` (string): Tool version to execute (defaults to "00000000_00" if not specified)
- `custom_auth_params` (object): Custom authentication parameters for tools that support parameterized authentication
  - `base_url` (string): The base URL (root address) what you should use while making http requests to the connected account. For example, for gmail, it would be 'https://gmail.googleapis.com'
  - `parameters` (array<object>)
    - Array items:
      - `name` (string) *(required)*: The name of the parameter. For example, 'x-api-key', 'Content-Type', etc.
      - `in` (enum: "query" | "header") *(required)*: The location of the parameter. Can be 'query' or 'header'.
      - `value` (any) *(required)*: The value of the parameter. For example, '1234567890', 'application/json', etc.
  - `body` (object): The body to be sent to the endpoint for authentication. This is a JSON object. Note: This is very rarely needed and is only required by very few apps.
    - `[key: string]` (any)
- `custom_connection_data` (object): Custom connection data for tools that support custom connection data
  - `authScheme` (enum: "OAUTH2" | "DCR_OAUTH" | "API_KEY" | ...) *(required)*
  - `toolkitSlug` (string) *(required)*
  - `val` (object) *(required)*
    - `subdomain` (string)
    - `your-domain` (string)
    - `region` (string)
    - `shop` (string)
    - `account_url` (string)
    - `COMPANYDOMAIN` (string)
    - `extension` (string)
    - `form_api_base_url` (string)
    - `instanceEndpoint` (string)
    - `api_url` (string)
    - `borneo_dashboard_url` (string)
    - `proxy_username` (string)
    - `proxy_password` (string)
    - `domain` (string)
    - `version` (string)
    - `dc` (string)
    - `site_name` (string)
    - `instanceName` (string)
    - `account_id` (string)
    - `your_server` (string)
    - `server_location` (string)
    - `base_url` (string)
    - `state_prefix` (string): The oauth2 state prefix for the connection
    - `long_redirect_url` (boolean): Whether to return the redirect url without shortening
    - `access_token` (string) *(required)*
    - `id_token` (string)
    - `token_type` (string)
    - `refresh_token` (string,null)
    - `expires_in` (any)
    - `scope` (any)
    - `webhook_signature` (string)
    - `authed_user` (object): for slack user scopes
      - `access_token` (string)
      - `scope` (string)
    - `client_id` (string): Dynamically registered client ID
    - `client_secret` (string): Dynamically registered client secret
    - `client_id_issued_at` (number)
    - `client_secret_expires_at` (number)
    - `generic_api_key` (string)
    - `api_key` (string)
    - `bearer_token` (string)
    - `basic_encoded` (string)
    - `username` (string)
    - `password` (string)
    - `token` (string)
    - `oauth_token` (string)
    - `oauth_token_secret` (string)
    - `oauth_verifier` (string)
    - `consumer_key` (string)
    - `redirectUrl` (string)
    - `callback_url` (string)
    - `application_id` (string)
    - `installation_id` (string)
    - `private_key` (string)
    - `credentials_json` (string)
    - `expires_at` (string)
    - `[key: string]` (any)
- `arguments` (object): Key-value pairs of arguments required by the tool (mutually exclusive with text)
  - `[key: string]` (any)
- `text` (string): Natural language description of the task to perform (mutually exclusive with arguments)
- `allow_tracing` (boolean,null): Deprecated. Enable debug tracing for tool execution (useful for debugging)

**Example:**

```json
{
  "connected_account_id": "string",
  "entity_id": "string",
  "user_id": "string",
  "version": "string",
  "custom_auth_params": {
    "base_url": "string",
    "parameters": [
      {
        "name": "...",
        "in": "...",
        "value": "..."
      }
    ],
    "body": {
      "key": null
    }
  },
  "custom_connection_data": {
    "authScheme": "OAUTH2",
    "toolkitSlug": "string",
    "val": {
      "subdomain": "string",
      "your-domain": "string",
      "region": "string",
      "shop": "string",
      "account_url": "string",
      "COMPANYDOMAIN": "string",
      "extension": "string",
      "form_api_base_url": "string",
      "instanceEndpoint": "string",
      "api_url": "string",
      "borneo_dashboard_url": "string",
      "proxy_username": "string",
      "proxy_password": "string",
      "domain": "string",
      "version": "string",
      "dc": "string",
      "site_name": "string",
      "instanceName": "string",
      "account_id": "string",
      "your_server": "string",
      "server_location": "string",
      "base_url": "string",
      "state_prefix": "string",
      "long_redirect_url": true,
      "access_token": "string",
      "id_token": "string",
      "token_type": "string",
      "refresh_token": null,
      "expires_in": null,
      "scope": null,
      "webhook_signature": "string",
      "authed_user": {
        "access_token": "...",
        "scope": "..."
      },
      "client_id": "string",
      "client_secret": "string",
      "client_id_issued_at": 1,
      "client_secret_expires_at": 1,
      "generic_api_key": "string",
      "api_key": "string",
      "bearer_token": "string",
      "basic_encoded": "string",
      "username": "string",
      "password": "string",
      "token": "string",
      "oauth_token": "string",
      "oauth_token_secret": "string",
      "oauth_verifier": "string",
      "consumer_key": "string",
      "redirectUrl": "string",
      "callback_url": "string",
      "application_id": "string",
      "installation_id": "string",
      "private_key": "string",
      "credentials_json": "string",
      "expires_at": "string",
      "key": null
    }
  },
  "arguments": {
    "key": null
  },
  "text": "string",
  "allow_tracing": null
}
```

### Responses

#### 200 - Successfully executed action and received response

**Response Schema:**

- `data` (object) *(required)*: Tool execution output data that varies based on the specific tool
  - `[key: string]` (any)
- `error` (string,null) *(required)*: Error message if the tool execution was not successful (null if successful)
- `successful` (boolean) *(required)*: Indicates if the tool execution was successful
- `session_info` (object,null): Optional session information for tools that return session context
- `log_id` (string): Unique identifier for the execution log (useful for debugging and support)

**Example Response:**

```json
{
  "data": {
    "key": null
  },
  "error": null,
  "successful": true,
  "session_info": null,
  "log_id": "string"
}
```

#### 400 - Bad request - Invalid request parameters, missing required arguments, or conflicting parameters

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 401 - Unauthorized - Authentication credentials are missing or invalid

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 403 - Forbidden - Connected account does not have permission to execute this tool or access the requested resource

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 404 - Not found - Tool or connected account not found

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 408 - Request timeout - Tool execution exceeded the maximum allowed time

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 410 - Gone - Tool has been deprecated and is no longer available

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 413 - Payload too large - Request or response payload exceeds size limits

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 422 - Unprocessable entity - Invalid state of the connected account

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 429 - Rate limit exceeded - Too many requests to the tool or underlying API

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 500 - Internal server error - Something went wrong on the server

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 501 - Not implemented

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 502 - Bad gateway - Error communicating with the tool provider API

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

#### 503 - Upstream service unavailable - Tool provider API is currently down or unavailable

**Response Schema:**

- `error` (object) *(required)*
  - `message` (string) *(required)*
  - `code` (number) *(required)*
  - `slug` (string) *(required)*
  - `status` (number) *(required)*
  - `request_id` (string)
  - `suggested_fix` (string)
  - `errors` (array<string>)

### Example cURL Request

```bash
curl -X POST "https://backend.composio.dev/api/v3.1/tools/execute/string" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "string",
    "entity_id": "string",
    "user_id": "string",
    "version": "string",
    "custom_auth_params": {
      "base_url": "string",
      "parameters": [
        {
          "name": "...",
          "in": "...",
          "value": "..."
        }
      ],
      "body": {
        "key": null
      }
    },
    "custom_connection_data": {
      "authScheme": "OAUTH2",
      "toolkitSlug": "string",
      "val": {
        "subdomain": "string",
        "your-domain": "string",
        "region": "string",
        "shop": "string",
        "account_url": "string",
        "COMPANYDOMAIN": "string",
        "extension": "string",
        "form_api_base_url": "string",
        "instanceEndpoint": "string",
        "api_url": "string",
        "borneo_dashboard_url": "string",
        "proxy_username": "string",
        "proxy_password": "string",
        "domain": "string",
        "version": "string",
        "dc": "string",
        "site_name": "string",
        "instanceName": "string",
        "account_id": "string",
        "your_server": "string",
        "server_location": "string",
        "base_url": "string",
        "state_prefix": "string",
        "long_redirect_url": true,
        "access_token": "string",
        "id_token": "string",
        "token_type": "string",
        "refresh_token": null,
        "expires_in": null,
        "scope": null,
        "webhook_signature": "string",
        "authed_user": {
          "access_token": "...",
          "scope": "..."
        },
        "client_id": "string",
        "client_secret": "string",
        "client_id_issued_at": 1,
        "client_secret_expires_at": 1,
        "generic_api_key": "string",
        "api_key": "string",
        "bearer_token": "string",
        "basic_encoded": "string",
        "username": "string",
        "password": "string",
        "token": "string",
        "oauth_token": "string",
        "oauth_token_secret": "string",
        "oauth_verifier": "string",
        "consumer_key": "string",
        "redirectUrl": "string",
        "callback_url": "string",
        "application_id": "string",
        "installation_id": "string",
        "private_key": "string",
        "credentials_json": "string",
        "expires_at": "string",
        "key": null
      }
    },
    "arguments": {
      "key": null
    },
    "text": "string",
    "allow_tracing": null
  }'
```