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

# Actions (deprecated)

> Compatibility reference for existing action functions and asynchronous action callers.

> [!WARNING]
>
> Actions are deprecated. For new development, use [Tools](https://nango.dev/docs/guides/functions/tools.md). Existing actions remain callable. See [Migrate from actions to tools](https://nango.dev/docs/guides/platform/migrations/migrate-from-actions.md) before changing an existing integration.

## Existing action definitions

Legacy actions use `createAction` from `nango`. Keep the original input and output schemas and read input from the second `exec` argument:

```typescript theme={null}
import { createAction } from 'nango';
import * as z from 'zod';

export default createAction({
    description: 'Reads a GitHub issue',
    input: z.object({ owner: z.string(), repo: z.string(), issueNumber: z.number() }),
    output: z.object({ title: z.string() }),
    exec: async (nango, input) => {
        const response = await nango.get({
            endpoint: `/repos/${input.owner}/${input.repo}/issues/${input.issueNumber}`
        });
        return { title: response.data.title };
    }
});
```

Keep importing the file from your project's `index.ts`. Existing projects can dry run actions with `nango dryrun <name> <connection-id> --input '<JSON>'` and deploy one with `nango deploy <environment> <integration>/actions/<file>.ts`.

## Synchronous calls

Prefer [calling the action through the tool-call API](https://nango.dev/docs/guides/functions/tools.md#call-a-tool). Existing callers can continue to use `nango.triggerAction(integrationId, connectionId, actionName, input)` or [`POST /action/trigger`](https://nango.dev/docs/reference/backend/http-api/action/trigger).

Legacy HTTP calls send `Connection-Id`, `Provider-Config-Key`, and `Content-Type: application/json` headers, with `{ "action_name": "<ACTION-NAME>", "input": {} }` as the body. Authenticate with a Nango Environment API key from **Environment Settings > API Keys**, sent as `Authorization: Bearer <NANGO-API-KEY>`. Scoped keys need `environment:tools:call`.

## Asynchronous calls

Existing async workflows can continue using the legacy API:

```typescript theme={null}
const { id, statusUrl } = await nango.triggerActionAsync(
    '<INTEGRATION-ID>',
    '<CONNECTION-ID>',
    '<ACTION-NAME>',
    { title: 'Example' }
);
const result = await nango.getAsyncActionResult({ id });
```

For HTTP, send the same request to `POST /action/trigger` with `X-Async: true`. Optionally set `X-Max-Retries` from `0` to `5`; the default is `0`. Use retries only when the operation is safe to repeat.

The response contains an `id` and `statusUrl`. Poll `GET /action/<ACTION-ID>`: `404` means the execution is still running, `200` returns the output, and `500` returns the execution error. Use the same authentication and scope as the trigger request.

Async actions are processed sequentially per environment; completion time depends on queue length and execution time. To receive completion events instead of polling, enable **Async action completed** in your [webhook configuration](https://nango.dev/docs/guides/functions/action-functions#completion-webhook).

## Calling an action from a function

Existing sync or action functions can call `await nango.triggerAction('<ACTION-NAME>', input)`. This helper is deprecated and is not available on the tool SDK.

## Action errors

Existing actions can throw `new nango.ActionError({ message: 'Example' })` to return an `action_script_failure` with the supplied payload. This is a legacy action error contract.

## Completion webhook

Enable **Async action completed** in the **Environment Settings** webhook configuration. Nango sends the completion payload to your configured webhook URL. Keep your existing handler and its payload contract while migrating synchronous callers to tools. See [webhook verification and retries](https://nango.dev/docs/guides/platform/webhooks-from-nango.md).

The completion webhook identifies the execution to poll:

```json theme={null}
{
    "from": "nango",
    "type": "async_action",
    "connectionId": "<CONNECTION-ID>",
    "providerConfigKey": "<INTEGRATION-ID>",
    "payload": {
        "id": "<ACTION-ID>",
        "statusUrl": "/action/<ACTION-ID>"
    }
}
```

Fetch the result from `payload.statusUrl` with your Environment API key. Verify the webhook signature before processing it.


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