# Importly > Importly is the video & audio MCP for AI agents. It downloads, transcribes, and extracts metadata from any media URL (YouTube, TikTok, X, Instagram, podcasts, and 1000+ other sites). It works from servers and agent sandboxes, with no IP blocks, bot checks, extractor breakage, or ffmpeg to deal with. The same API key works in the MCP server and in production apps via the REST API. New accounts get $3.00 in free credits with no card required: https://www.importly.io/login?mode=signup. The API key is at https://www.importly.io/dashboard/api-key. ## Connect via MCP Hosted MCP server (Streamable HTTP): https://mcp.importly.io/mcp. Nothing to install. Coding agents authenticate with the API key as an `Authorization: Bearer ` header. Claude.ai, ChatGPT, and Claude Desktop add the URL as a custom connector and sign in with OAuth instead (no key). Claude Code: ```bash claude mcp add --transport http importly https://mcp.importly.io/mcp --header "Authorization: Bearer your_key" ``` Cursor and other clients that accept a remote URL and headers (JSON config; field names vary by client, e.g. Cline also needs `"type": "streamableHttp"`): ```json { "mcpServers": { "importly": { "url": "https://mcp.importly.io/mcp", "headers": { "Authorization": "Bearer your_key" } } } } ``` Tools: import_media / check_import (download to hosted storage, returns a direct media URL), transcribe_media / check_transcription (timestamped transcript; pass provider "importly" for media without captions), get_metadata / check_metadata (formats, uploader, stats), get_basic_metadata / check_basic_metadata (fast title/duration/thumbnail), check_balance, get_integration_guide (code for adding Importly to the user's app; no credits). Submit tools return a jobId; poll the matching check tool. ## Integrate Importly into an app When a user asks you to add Importly to their application, use the REST API at https://api.importly.io: - Auth: `Authorization: Bearer $IMPORTLY_API_KEY`. Read the key from an environment variable on the server; never hardcode it or ship it to the browser. - Jobs are async: `POST /import`, `POST /transcribe`, or `POST /metadata` with `{ "url": "..." }` returns `{ "success": true, "data": { "jobId": "..." } }`. - Results by webhook: pass `webhookUrl` to receive one POST when the job succeeds. Result fields are flattened into `data` (e.g. `data.mediaUrl`, `data.text`), not nested under `result`. Failed jobs do not fire webhooks and there are no retries, so keep a polling fallback. - Results by polling: `GET /import/status?id=` (likewise `/transcribe/status`, `/metadata/status`) until `status` is `completed` or `failed`. Completed jobs nest fields under `result` (e.g. `result.mediaUrl`). - Errors: 401 bad key, 402 insufficient credits, 429 rate limited (back off and retry). Status endpoints allow 3,600 requests per hour per key (about 1/second), so poll every few seconds rather than in a tight loop. - Optional: deliver files straight to the user's own S3 bucket (see the S3 storage page below). - Pricing: about $0.01/MB downloaded, $0.02/min for transcription. See https://www.importly.io/pricing. Full docs as a single markdown file: https://www.importly.io/docs/llms-full.txt ## Docs ### Get started - [Introduction](https://www.importly.io/docs/introduction.md): Download, transcribe, and read metadata from any public video or audio URL, from your AI agent or your app. - [Use Importly in your AI agent](https://www.importly.io/docs/integrations/mcp.md): Connect Claude, ChatGPT, Cursor, Claude Code, or any MCP client to Importly's hosted MCP server, so your agent can download, transcribe, and read metadata from any video URL. - [Quick start](https://www.importly.io/docs/quick-start.md): Your first import in three steps: get a key, submit a URL with cURL, Node.js, or Python, and collect the result. - [Authentication](https://www.importly.io/docs/authentication.md): Bearer API key auth, keeping keys server-side, and rotating keys. - [Pricing & credits](https://www.importly.io/docs/billing.md): Pay-as-you-go prices for imports, metadata, and transcription, how charges and refunds work, and what happens at low balance. ### Features - [Download media](https://www.importly.io/docs/features/downloads.md): Download video or audio from a public URL at the quality you choose and get a direct link, or have it copied to your own S3 bucket. - [Transcripts](https://www.importly.io/docs/features/transcripts.md): Get a timestamped transcript for any public video or audio URL. Importly uses the video's own captions when it has them and AI speech-to-text when it doesn't. - [Metadata](https://www.importly.io/docs/features/metadata.md): Read a video's title, duration, uploader, thumbnails, view counts, and available formats without downloading it. - [Deliver to your bucket](https://www.importly.io/docs/s3-storage.md): Deliver imports to your own S3, R2, B2, or Spaces bucket: bucket and IAM setup, usage, and troubleshooting. - [Webhooks](https://www.importly.io/docs/webhooks.md): Get job results pushed to your URL instead of polling: payload shape per job type, success-only single delivery, and handler tips. - [Supported sites](https://www.importly.io/docs/features/supported-sites.md): Which URLs Importly can fetch: public videos and audio on YouTube, TikTok, X, Instagram, Vimeo, podcasts, and 1000+ other sites, plus direct media file links. ### AI agents - [MCP tools](https://www.importly.io/docs/integrations/mcp-tools.md): Every tool on Importly's MCP server: what it does, its inputs, what it costs, and how an agent collects the result of an async job. - [Build with your agent](https://www.importly.io/docs/integrations/build-with-your-agent.md): Have the coding agent that already uses Importly's MCP server add downloads, transcripts, or metadata to your app with the same API key. ### Errors & limits - [Errors & rate limits](https://www.importly.io/docs/error-handling.md): Status codes, error shapes, per-key rate limits, rate-limit headers, and when to retry. ### Error codes - [Unauthorized](https://www.importly.io/docs/errors/unauthorized.md): The request had no API key, or the key isn't valid. HTTP 401, code UNAUTHORIZED. - [Insufficient credits](https://www.importly.io/docs/errors/insufficient-credits.md): Your balance is too low to start the job, or to pay for the whole download. HTTP 402, code INSUFFICIENT_BALANCE or FILE_TOO_LARGE. - [Rate limited](https://www.importly.io/docs/errors/rate-limited.md): You sent more requests to this endpoint than your hourly limit allows. HTTP 429, code RATE_LIMITED. - [Invalid URL](https://www.importly.io/docs/errors/invalid-url.md): The url is missing, malformed, not a media page, or a playlist. HTTP 400 or a failed job, code INVALID_URL or PLAYLIST_NOT_SUPPORTED. - [Invalid request](https://www.importly.io/docs/errors/invalid-request.md): A parameter is missing or has a value Importly can't use. HTTP 400, code INVALID_REQUEST. - [Not found](https://www.importly.io/docs/errors/not-found.md): No job with that ID belongs to your API key, or there are no saved settings. HTTP 404, code NOT_FOUND. - [Media unavailable](https://www.importly.io/docs/errors/media-unavailable.md): The job was accepted, but the media can't be fetched: it's private, deleted, age-restricted, region-locked, needs a login, or is still live. - [Source throttled](https://www.importly.io/docs/errors/source-throttled.md): The platform refused the request for a moment. Retrying a little later usually works. Code SOURCE_THROTTLED on a failed job. - [Transcription needs speech-to-text](https://www.importly.io/docs/errors/transcription-provider-required.md): The video has no captions and no provider was set, or speech-to-text would cost more than maxCostDollars. Codes TRANSCRIPTION_PROVIDER_REQUIRED and MAX_COST_EXCEEDED. - [Server error](https://www.importly.io/docs/errors/server-error.md): Something failed on Importly's side. HTTP 500 or a failed job, code INTERNAL_ERROR, BILLING_UNAVAILABLE, or UNKNOWN_ERROR. Retry with backoff. ### Using the API - [API reference](https://www.importly.io/docs/api-reference.md): Base URL, Bearer authentication, the response envelope, status codes, and the async job model of the Importly REST API. ### Media - [Import media](https://www.importly.io/docs/endpoints/import.md): Download media from a URL to hosted storage or your S3 bucket, with quality options, optional transcript, and status polling. - [Get import status](https://www.importly.io/docs/endpoints/import-status.md): Poll an import job until it's completed or failed. Completed jobs carry the download link, file details, and cost. ### Transcripts - [Transcribe media](https://www.importly.io/docs/endpoints/transcribe.md): Transcribe any media URL: source captions, built-in AI speech-to-text, or your own provider key; timestamped segments. - [Get transcription status](https://www.importly.io/docs/endpoints/transcribe-status.md): Poll a transcription job until it's completed or failed. Completed jobs carry the text and timestamped segments. ### Metadata - [Get metadata](https://www.importly.io/docs/endpoints/metadata.md): Full media metadata (formats, uploader, thumbnails, stats) without downloading. - [Get metadata status](https://www.importly.io/docs/endpoints/metadata-status.md): Poll a metadata job until it's completed or failed. Completed jobs carry the source's full metadata. - [Get basic metadata](https://www.importly.io/docs/endpoints/basic-metadata.md): Fast title, duration, and thumbnail lookup for a URL. - [Get basic metadata status](https://www.importly.io/docs/endpoints/basic-metadata-status.md): Poll a basic metadata job until it's completed or failed. Completed jobs carry the title, duration, and thumbnail. - [Get metadata (GET form)](https://www.importly.io/docs/endpoints/metadata-get.md): Start a full metadata job with the URL as a query parameter. Same as POST /metadata, without a webhook. - [Get basic metadata (GET form)](https://www.importly.io/docs/endpoints/basic-metadata-get.md): Start a basic metadata job with the URL as a query parameter. Same as POST /metadata/basic, without a webhook. ### Account - [Get balance](https://www.importly.io/docs/endpoints/balance.md): Check your remaining Importly credit balance via the API. ### Account settings - [Get S3 storage settings](https://www.importly.io/docs/endpoints/get-s3-storage.md): Read your saved S3-compatible storage settings. The secret access key is never returned. - [Save S3 storage settings](https://www.importly.io/docs/endpoints/save-s3-storage.md): Save the bucket and credentials that imports with store: true upload to. The connection is tested before saving. - [Delete S3 storage settings](https://www.importly.io/docs/endpoints/delete-s3-storage.md): Remove your saved S3 storage settings. Imports with store: true stop uploading to your bucket. - [Test S3 storage settings](https://www.importly.io/docs/endpoints/test-s3-storage.md): Check bucket credentials by uploading a small test file, without saving them. - [List transcription provider keys](https://www.importly.io/docs/endpoints/list-transcription-providers.md): List the speech-to-text providers you've saved a key for. Keys are never returned. - [Save a transcription provider key](https://www.importly.io/docs/endpoints/save-transcription-provider.md): Store your AssemblyAI, Deepgram, or OpenAI key so transcriptions with that provider don't need apiKey. - [Delete a transcription provider key](https://www.importly.io/docs/endpoints/delete-transcription-provider.md): Remove a saved speech-to-text provider key. ### Webhook payloads - [Import completed webhook](https://www.importly.io/docs/endpoints/webhooks/import.md): The payload Importly POSTs to your webhookUrl when an import succeeds. - [Transcription completed webhook](https://www.importly.io/docs/endpoints/webhooks/transcribe.md): The payload Importly POSTs to your webhookUrl when a transcription succeeds. - [Metadata completed webhook](https://www.importly.io/docs/endpoints/webhooks/metadata.md): The payload Importly POSTs to your webhookUrl when a metadata job succeeds. - [Basic metadata completed webhook](https://www.importly.io/docs/endpoints/webhooks/basic-metadata.md): The payload Importly POSTs to your webhookUrl when a basic metadata job succeeds.