> ## Documentation Index
> Fetch the complete documentation index at: https://docs.60db.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Integration Action

> Run one action of a connection now. It uses the same code path as a live agent call

Run one action of a connection now, without a call. The action runs through the same code as an agent tool during a call: the same argument checks, the same provider adapter or MCP client, and the same 16 KB result cap.

`action` is a curated action key for a key provider, such as `search_contact`. For a custom MCP server it is the tool name. For a custom webhook it is `call`. The action must appear in [List integration tools](https://docs.60db.ai/api-reference/agents/list-integration-tools.md) for the connection.

The whole call has a 15 second budget. Every call is written to the activity log with the connection, the action and the outcome. Arguments and secrets are not logged.

## Request

### Headers

**Authorization** `string` *required*

Bearer token with your API key (scope `agents`)

**Content-Type** `string` *required*

application/json

### Path

**id** `string` *required*

The connection `id` (UUID)

**action** `string` *required*

The action key, up to 64 characters

### Body

**arguments** `object` (default: \{})

The arguments of the action. An object of at most 8 KB when serialized. Check each argument against the tool's `parameters` first. Other top-level keys are refused

## Response

**200 OK**

```json theme={null}
{
  "success": true,
  "data": {
    "ok": true,
    "result": { "contacts": [] }
  }
}
```

`result` is what the action returns. Its shape depends on the action. A result over 16 KB is replaced by `{ "truncated": true, "preview": "..." }`, where `preview` is the first 2,000 characters of the JSON.

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | `VALIDATION_ERROR` | The body is not an object, or has a top-level key other than `arguments` |
| 403 | `POLICY_DENY` | Your role cannot use integrations, or the API key lacks the `agents` scope |
| 404 | `INTEGRATION_NOT_FOUND` | No connection with this ID in your workspace |
| 404 | `INTEGRATION_ACTION_NOT_FOUND` | The connection does not offer this action |
| 413 | `ARGUMENTS_TOO_LARGE` | `arguments` is larger than 8 KB |
| 422 | `INTEGRATION_BAD_ARGUMENTS` | An argument is missing, has the wrong JSON type, or fails the provider's check. `field` is `arguments`. The message names the key. For a choice list (`enum`), it also names the allowed values |
| 422 | `INTEGRATION_PROVIDER_REMOVED` | The provider is no longer offered. Delete the connection |
| 429 | `RATE_LIMITED` | More than 60 actions in the last minute. This is this API's own limit |
| 502 | `INTEGRATION_AUTH_FAILED` | The provider rejected the credentials |
| 502 | `INTEGRATION_RATE_LIMITED` | The provider is rate limiting. This is not your 429 limit |
| 502 | `INTEGRATION_NOT_FOUND` | The provider answered 404. The record the action asked for may not exist |
| 502 | `INTEGRATION_REQUEST_REJECTED` | The provider refused the request |
| 502 | `INTEGRATION_UPSTREAM_ERROR` | The provider had an internal error |
| 502 | `INTEGRATION_UNREACHABLE` | The provider could not be reached |
| 502 | `INTEGRATION_TOOL_ERROR` | The tool reported an error |
| 502 | `INTEGRATION_BAD_RESPONSE` | The provider answered with something that is not valid JSON |
| 502 | `INTEGRATION_MCP_ERROR` | The MCP server returned an invalid answer |
| 502 | `INTEGRATION_RESPONSE_TOO_LARGE` | The provider's answer is larger than 256 KB |
| 504 | `INTEGRATION_TIMEOUT` | The call ran past the 15 second budget |

Failures at the provider are `502`, so `429` always means your own limit. The `code` names the cause. The `message` is a fixed text. The provider's own words are never returned.

## Example

```bash cURL theme={null}
curl -X POST https://api.60db.ai/agents/integrations/INTEGRATION_ID/actions/search_contact \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"arguments": {"email": "jane@acme.com"}}'
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.