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

# Use Importly from n8n

> Get transcripts, video files and metadata from any link in an n8n workflow with the built-in HTTP Request node: a Header Auth credential, a one-node transcript, and a file import with a webhook or a polling loop.

A workflow that downloads a video or pulls a transcript often works in a test run and then fails on n8n Cloud or a VPS, because sites block datacenter IPs and many videos have no captions. Your workflow can send the link to Importly with n8n's built-in **HTTP Request** node and get the transcript, file or metadata back. No community node or code is needed.

## 1. Add your key as a credential

Create your key on the [API key page](https://www.importly.io/dashboard/api-key) (it is shown once). In n8n, open **Credentials**, create a **Header Auth** credential and set:

| Field | Value |
| - | - |
| Name | `Authorization` |
| Value | `Bearer YOUR_API_KEY` |

Every HTTP Request node below uses **Authentication: Generic Credential Type**, **Generic Auth Type: Header Auth**, and this credential. The key stays out of the workflow JSON, so you can share or export the workflow safely.

## 2. Get a transcript in one node

Add an **HTTP Request** node after your trigger (a form, a schedule, a new row in a sheet):

| Setting | Value |
| - | - |
| Method | `POST` |
| URL | `https://api.importly.io/transcribe` |
| Send Body | On, **Body Content Type** JSON, **Specify Body** Using JSON |

```json JSON body theme={null}
{
  "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
  "mode": "auto",
  "wait": true,
  "maxCostDollars": 0.5
}
```

To take the link from the previous node, replace the URL with an expression such as `{{ $json.videoUrl }}`.

`"mode": "auto"` uses the video's captions and falls back to speech-to-text when it has none. `"wait": true` holds the request open for up to 30 seconds, so a caption transcript usually comes back in this node's output:

| Field | Expression |
| - | - |
| Status | `{{ $json.data.status }}` |
| Transcript text | `{{ $json.data.result.text }}` |
| Timed segments | `{{ $json.data.result.data.segments }}` |
| Cost | `{{ $json.data.result.costInDollars }}` |

If `status` is still `running` (long videos transcribed from audio), finish it with the polling loop in step 3, using `GET https://api.importly.io/transcribe/status?id=...`. A caption transcript costs \$0.003; see [Pricing & credits](/docs/billing.md).

## 3. Import a file

`POST /import` starts a download and returns a `jobId` right away. Collect the file with an n8n Webhook node, or poll until it's done.

> [tab] Webhook
>
> Make a second workflow that starts with a **Webhook** node (HTTP Method `POST`) and activate it. Copy its **Production URL**. It must be a public `https://` address, so this works on n8n Cloud or a self-hosted n8n behind a domain, not on `localhost`.
>
> In the first workflow, add an **HTTP Request** node: `POST https://api.importly.io/import` with this JSON body:
>
> ```json JSON body theme={null}
> {
>   "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
>   "videoQuality": "720p",
>   "webhookUrl": "https://your-n8n.example.com/webhook/importly"
> }
> ```
>
> When the job finishes, Importly sends one `POST` to the Webhook node. The result fields sit directly on `data`, so in the nodes after it the file link is `{{ $json.body.data.mediaUrl }}` and the title is `{{ $json.body.data.title }}`. A failed job arrives with `success: false` and a `message` ([Failed jobs](/docs/webhooks.md#failed-jobs)), so add an **IF** node on `{{ $json.body.success }}`.

> [tab] Polling
>
> Chain four nodes in one workflow:
>
> 1. An **HTTP Request** node sends `POST https://api.importly.io/import` with the body `{ "url": "...", "videoQuality": "720p" }`.
> 2. A **Wait** node pauses for 10 seconds.
> 3. A second **HTTP Request** node calls `GET https://api.importly.io/import/status?id={{ $json.data.jobId }}`.
> 4. An **IF** node checks that `{{ $json.data.status }}` is equal to `completed`.
>
> Connect the IF node's **false** branch back to the Wait node, so the loop checks again every 10 seconds. The status response has the same `data.jobId`, so step 3 keeps working on each pass. Add a second condition or a Switch node for `failed`, so a failed job leaves the loop instead of waiting forever.
>
> On the **true** branch the file link is `{{ $json.data.result.mediaUrl }}`. Polling nests the result under `result`, the webhook doesn't.

`mediaUrl` is a signed link that expires after 7 days. To keep the file, add an HTTP Request node that downloads it (**Response Format: File**) and an upload node for Google Drive or S3, or have every import land in [your own bucket](/docs/integrations/save-to-bucket.md).

## Metadata only

For a title, duration and thumbnail without downloading anything, use `POST https://api.importly.io/metadata/basic` with `{ "url": "..." }` and the same polling loop against `/metadata/basic/status`. See [Metadata](/docs/features/metadata.md).

## When a node fails

The HTTP Request node marks the run as failed on a `4xx` or `5xx` response. The JSON body says why, with a `code` such as `INSUFFICIENT_BALANCE` or `INVALID_URL`. Turn on the node's **Continue On Fail** setting (or **On Error: Continue**) if you want to branch on the error instead of stopping. Every code is listed in [Errors](/docs/error-handling.md). Using Make or Zapier instead? See [Make](/docs/integrations/make.md) or [Zapier](/docs/integrations/zapier.md).


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