# How to Use the n8n API (Keys, Endpoints, Pagination)

> In n8n, go to Settings > n8n API and create an API key. Send it in the X-N8N-API-KEY header to https://<your-instance>/api/v1 (n8n Cloud: https://<name>.app.n8n.cloud/api/v1). Lists return up to 100 items by default and 250 at most, with a nextCursor for the next page. The API is on every self-hosted edition and on Cloud Starter and up, but not on the free trial.

Source page: https://aiwiserank.com/guides/n8n-api · Last checked: 2026-10-27 · Tool: n8n

## What the n8n API is for

n8n's public REST API lets you do from code most of what you do in the editor: list, create and update workflows, activate or deactivate them, read executions, and manage credentials, tags and users. It's useful for:
- deploying workflows from Git;
- backing up an instance;
- building dashboards on top of execution data.

This is **not** the same as calling a workflow through a **Webhook** node. A Webhook node gives one workflow its own URL. The API manages the n8n instance itself.

## Which plans include it

| n8n edition | API available? |
|---|---|
| Self-hosted (any edition) | Yes |
| n8n Cloud Starter, Pro, Enterprise | Yes |
| n8n Cloud free trial | No |

## Step 1: Create an API key

1. In n8n, open **Settings > n8n API**.
2. Select **Create an API key**.
3. Give it a **label** and choose an **expiration**.
4. On **Enterprise** plans you can also pick **scopes**, which limit what the key can do. Choose the fewest the job needs. On other plans, a key has full access to everything your account can do, so treat it like a password.
5. Copy the key. You won't be able to see it again.

To revoke a key, go back to **Settings > n8n API**, select **Delete** next to it, then **Delete Forever**.

## Step 2: Find your base URL

| Where n8n runs | Base URL |
|---|---|
| n8n Cloud | `https://<name>.app.n8n.cloud/api/v1` |
| Self-hosted | `https://<your-instance-url>/api/v1` |

For a local Docker install, that's `http://localhost:5678/api/v1`. If you serve n8n under a sub-path, the path goes before `/api`.

## Step 3: Make your first request

List your active workflows:

```shell
curl -X GET \
  'https://<your-instance-url>/api/v1/workflows?active=true' \
  -H 'accept: application/json' \
  -H 'X-N8N-API-KEY: <your-api-key>'
```

The header name is exactly `X-N8N-API-KEY`. A wrong or missing key returns **401 Unauthorized**.

## Step 4: Page through results

List endpoints return results in pages:

- **`limit`** sets the page size: **100** by default, **250** at most.
- Each response has a **`nextCursor`** value. Pass it as **`cursor`** to get the next page.
- When `nextCursor` is `null`, you've reached the last page.

```shell
# first page
curl -H 'X-N8N-API-KEY: <your-api-key>' \
  'https://<your-instance-url>/api/v1/workflows?active=true&limit=150'

# next page: use the nextCursor value from the previous response
curl -H 'X-N8N-API-KEY: <your-api-key>' \
  'https://<your-instance-url>/api/v1/workflows?active=true&limit=150&cursor=<nextCursor>'
```

Responses have the shape `{ "data": [ ... ], "nextCursor": "..." }`.

## Avoid duplicates when retrying

For `POST` requests, n8n supports an **`Idempotency-Key`** header. Send the same key when you retry a request that may have timed out, and n8n won't create the item twice.

## Try endpoints in the API playground

Self-hosted instances include an interactive **API playground** where you can try each endpoint with your key; see n8n's [API docs](https://docs.n8n.io/api/). It isn't available on n8n Cloud. The full endpoint reference is generated from n8n's OpenAPI specification.

## Common problems

- **401 Unauthorized.** The header name is wrong, or the key has expired or been deleted. Create a new key.
- **The API option is missing in Settings.** You're on the n8n Cloud free trial; the API needs a paid Cloud plan or a self-hosted instance.
- **Only part of the list came back.** You got the first page. Follow `nextCursor` as shown above.

## Sources

- https://docs.n8n.io/api/
- https://docs.n8n.io/connect/n8n-api/authentication/
- https://docs.n8n.io/connect/n8n-api/pagination/