How async jobs work
Downloads, transcripts, and metadata run as jobs. Each submit tool returns ajobId right away, along with a reminder to poll:
status is completed or failed. Check tools are free.
import_media
Downloads the video or audio at a URL to hosted storage and returns a direct download link. Costs $0.01 per MB downloaded, with a $0.03 minimum, charged only when the download succeeds.check_import returns mediaUrl (valid for 7 days), title, duration, fileSizeBytes, downloadedBytes, costInDollars, and the transcript if you asked for one. See Download media.
transcribe_media
Returns the transcript text and timestamped segments.
Without
provider, it uses the video’s captions for $0.01. If there are none, the job fails at no charge with a `TRANSCRIPTION_PROVIDER_REQUIRED` quote, and the agent can retry with `provider: "importly"` ($0.02 per minute, $0.03 minimum, plus the audio download). Failed transcriptions are refunded. See Transcripts.
Your own AssemblyAI, Deepgram, or OpenAI key works through the REST API (
provider plus apiKey), not through the MCP tool.get_metadata
Full metadata without downloading: title, description, duration, uploader, formats, thumbnails, and view counts. $0.01. Input:url. See Metadata.
get_basic_metadata
Title, duration, and thumbnail only. Faster thanget_metadata, and useful to check a URL before importing or transcribing it. $0.01. Input: url.
check_balance
Returns the remaining credit, for exampleImportly credit balance: $2.97 USD. Free. No inputs. Agents use it to explain a failed job or check before a large import.
get_integration_guide
Returns working code for adding Importly to your own app: API key setup, starting a job, receiving the result by webhook or polling, and error handling. It doesn’t call the API and uses no credits.
See Build with your agent.