> ## 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 Pipedream

> Get transcripts, video files and metadata from any link in a Pipedream workflow: one Node.js code step for a transcript, and a file import collected by an HTTP trigger.

A workflow that downloads a video or pulls a transcript often works once and then fails, because sites block the datacenter IPs Pipedream runs on and many videos have no captions. Your workflow can send the link to Importly from a Node.js code step and get the transcript, file or metadata back. No custom app or extra packages are needed.

## 1. Store your key

Create your key on the [API key page](https://www.importly.io/dashboard/api-key) (it is shown once). In Pipedream, open **Settings > Environment Variables**, click **New Variable**, name it `IMPORTLY_API_KEY` and paste the key. Leave **Secret** on, so the value is never shown in the UI.

Code steps read it as `process.env.IMPORTLY_API_KEY`. You can revoke the key on the API key page at any time.

## 2. Get a transcript in one step

Add a step after your trigger (a schedule, a new row in Google Sheets, an HTTP request): click **+**, choose **Run custom code**, and paste:

```javascript Node.js code step theme={null}
export default defineComponent({
  async run({ steps, $ }) {
    const res = await fetch("https://api.importly.io/transcribe", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.IMPORTLY_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        url: "https://www.youtube.com/watch?v=jNQXAC9IVRw",
        mode: "auto",
        wait: true,
        maxCostDollars: 0.5,
      }),
    })
    const body = await res.json()
    if (!res.ok) throw new Error(`${body.code}: ${body.error}`)

    const { status, jobId, result } = body.data
    return { status, jobId, text: result?.text, segments: result?.data?.segments }
  },
})
```

To take the link from the trigger, replace the sample link with a value from `steps`, for example `steps.trigger.event.body.url` for an HTTP trigger.

`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 step. What the step returns is available to later steps as `steps.<step name>.$return_value`.

If `status` is still `running` (long videos transcribed from audio), check it again with `GET https://api.importly.io/transcribe/status?id=...` using the `jobId`. 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. The file is ready a few seconds to a few minutes later, so collect it with a second workflow that starts on an HTTP trigger.

1. Create a new workflow with the **HTTP / Webhook** trigger and copy its endpoint URL (`https://<id>.m.pipedream.net`). Deploy it.

2. In your first workflow, add a code step like the one above that calls `POST https://api.importly.io/import` with this body:

   ```json theme={null}
   {
     "url": "https://www.youtube.com/watch?v=jNQXAC9IVRw",
     "videoQuality": "720p",
     "webhookUrl": "https://your-endpoint-id.m.pipedream.net"
   }
   ```

3. When the job finishes, Importly sends one `POST` to the endpoint, and the second workflow runs with the result in `steps.trigger.event.body`.

In the webhook workflow the result fields sit directly on `data`: `steps.trigger.event.body.data.mediaUrl` is the file link and `steps.trigger.event.body.data.title` the title. A failed job arrives with `success` set to `false` and a `message` ([Failed jobs](/docs/webhooks.md#failed-jobs)), so check `success` before the steps that use the file. Deliveries are signed; to reject forged requests, see [Verify signatures](/docs/webhooks.md#verify-signatures).

`mediaUrl` is a signed link that expires after 7 days. To keep the file, add a step that uploads it to Google Drive, Dropbox 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, call `POST https://api.importly.io/metadata/basic` with `{ "url": "..." }` from a code step, then check `/metadata/basic/status` the same way. See [Metadata](/docs/features/metadata.md).

## When a step fails

The code above throws on a `4xx` or `5xx` response, which stops the workflow and shows the error. The JSON body says why, with a `code` such as `INSUFFICIENT_BALANCE` or `INVALID_URL`. Every code is listed in [Errors](/docs/error-handling.md). Using n8n, Make or Zapier instead? See [n8n](/docs/integrations/n8n.md), [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.