Node.js SDK
Convert files between 240+ formats from Node.js. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. Node.js 18+, typed, ESM and CommonJS, no dependencies.
Installing
Install it with your package manager. Node.js 18+ · TypeScript.
$ npm install @runconvert/sdk$ pnpm add @runconvert/sdk$ yarn add @runconvert/sdk$ bun add @runconvert/sdkInitializing
new RunConvert({ apiKey?, baseUrl?, timeout?, maxRetries?, fetch? })Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code.
Example
import { RunConvert } from "@runconvert/sdk";
const rc = new RunConvert(); // reads RUNCONVERT_API_KEYimport { RunConvert } from "@runconvert/sdk";
const rc = new RunConvert({
apiKey: process.env.RUNCONVERT_API_KEY,
timeout: 60_000,
maxRetries: 2,
});Parameters
apiKeystringYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.baseUrlstringDefaults to https://api.runconvert.com/v3.timeoutnumberMilliseconds per API request. Default 60 000. Uploads and downloads have no limit.maxRetriesnumberRetries for network errors, 429 and 5xx. Default 2.fetchtypeof fetchA custom fetch, for proxies or tests.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.
Example
import { RunConvert } from "@runconvert/sdk";
const rc = new RunConvert();
const { saved } = await rc.convert("report.docx", { to: "pdf", outDir: "out" });
console.log(saved); // [ 'out/report.pdf' ][ 'out/report.pdf' ]Convert
Convert a file
rc.convert(input, { to, from?, options?, outDir?, filename?, tag?, onUpdate?, timeout? }) → Promise<ConvertResult>Converts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.
Example
const { saved } = await rc.convert("report.docx", { to: "pdf", outDir: "out" });
console.log(saved);// Imported by RunConvert: nothing to upload
const { saved } = await rc.convert("https://example.com/talk.mp4", {
to: "mp3",
outDir: "out",
});await rc.convert("talk.mp4", {
to: "mp3",
options: { audioBitrate: "192k" },
outDir: "out",
});await rc.convert("movie.mov", {
to: "mp4",
outDir: "out",
onUpdate: (job) => console.log(job.status),
timeout: 10 * 60_000,
});[ 'out/report.pdf' ][ 'out/talk.mp3' ]waiting
processing
finishedParameters
inputstring | Uint8Array | Blob | ReadableStreamA local path, an http(s) URL (imported by RunConvert, nothing to upload), bytes, or a binary file or stream.RequiredtostringThe target format, e.g. "pdf" or "mp3".RequiredfromstringThe source format. Read from the file name or URL when left out; needed for bytes or streams without a filename.optionsRecord<string, unknown>Engine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair.outDirstringSave the results in this folder (created if needed). Without it nothing is downloaded; use the result's files.filenamestringThe file's name when you pass bytes or a stream.tagstringA label to find the job later, e.g. "invoices".onUpdate(job: Job) => voidCalled with the job after every check, e.g. to show progress.timeoutnumberMilliseconds to wait for the job before giving up.
Returns
ConvertResult: { job, files, saved }: the finished job, its result files (filename, url, size) and the local paths when outDir is set.
Jobs
Create a job
rc.jobs.create({ tasks, tag?, metadata? }) → Promise<Job>Creates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to.
Example
const job = await rc.jobs.create({
tag: "merge",
tasks: {
a: { operation: "import/url", source_url: "https://example.com/cover.pdf" },
b: { operation: "import/url", source_url: "https://example.com/body.pdf" },
merge: { operation: "convert", input: ["a", "b"], input_format: "pdf", output_format: "pdf" },
export: { operation: "export/url", input: "merge" },
},
});const job = await rc.jobs.create({
tasks: {
upload: { operation: "import/direct/upload" },
convert: { operation: "convert", input: "upload", input_format: "png", output_format: "webp", image_quality: 80 },
export: { operation: "export/url", input: "convert" },
},
});
await rc.files.upload(job.tasks!.find((t) => t.name === "upload")!, "image.png");Parameters
tasksRecord<string, TaskDefinition>Named task definitions. Names use letters, digits, - or _ (up to 64 characters).RequiredtagstringA label to find the job later, e.g. "invoices".metadataRecord<string, unknown>Your own key-value data, returned with the job and in webhooks.
Returns
The job, with its tasks.
Get a job
rc.jobs.get(id) → Promise<Job>Gets one job with its tasks: status, credits used, and the result files of its export tasks.
Example
const job = await rc.jobs.get("job_01hx4k9m2p7w");
console.log(job.status);{
"id": "job_01hx4k9m2p7w",
"status": "finished",
"tag": "invoices",
"credits_used": 2,
"created_at": "2026-11-16T09:12:04Z",
"ended_at": "2026-11-16T09:12:09Z",
"tasks": [
{ "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
{ "name": "convert-1", "operation": "convert", "status": "finished" },
{ "name": "export-1", "operation": "export/url", "status": "finished",
"result": { "files": [
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
] } }
]
}Parameters
idstringThe job's ID.Required
Returns
The job, with its tasks.
List jobs
rc.jobs.list({ status?, tag?, page?, perPage?, includeTasks? }) → Promise<Page<Job>>One page of jobs, newest first, with paging details. Filter by status or tag.
Example
const page = await rc.jobs.list({ status: "finished", perPage: 20 });
for (const job of page.data) console.log(job.id);{
"data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
"meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}Parameters
statusJobStatusOnly jobs with this status: waiting, processing, finished, error or canceled.tagstringA label to find the job later, e.g. "invoices".pagenumberPage number, from 1.perPagenumberJobs per page (max 100).includeTasksbooleanInclude each job's tasks.
Returns
One page: { data: Job[], meta: { page, per_page, total, total_pages } }.
Every job
rc.jobs.all({ status?, tag?, perPage?, includeTasks? }) → AsyncGenerator<Job>Every job, page by page, so you can loop over all of them without handling pages yourself.
Example
for await (const job of rc.jobs.all({ tag: "invoices" })) {
console.log(job.id, job.status);
}Parameters
filtersobjectThe same filters as list(), without page.
Wait for a job
rc.jobs.wait(id, { timeout?, onUpdate?, throwOnError?, signal? }) → Promise<Job>Polls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.
Example
const done = await rc.jobs.wait(job.id, { timeout: 5 * 60_000 });
for (const file of Jobs.exportedFiles(done)) await rc.files.download(file, "out");import { JobFailedError } from "@runconvert/sdk";
try {
await rc.jobs.wait(job.id);
} catch (e) {
if (e instanceof JobFailedError) console.log(e.task?.code, e.task?.reason, e.message);
}Parameters
idstringThe job's ID.RequiredtimeoutnumberMilliseconds to wait. Throws WaitTimeoutError after it.onUpdate(job: Job) => voidCalled with the job after every check, e.g. to show progress.throwOnErrorbooleanFail when the job ends in error (default). Turn off to get the failed job back instead.signalAbortSignalStop waiting when aborted.
Returns
The finished job.
Cancel a job
rc.jobs.cancel(id) → Promise<Job>Cancels a job's pending tasks. Credits for tasks that didn't finish are refunded.
Example
await rc.jobs.cancel("job_01hx4k9m2p7w");Parameters
idstringThe job's ID.Required
Returns
The canceled job.
Delete a job
rc.jobs.delete(id) → Promise<void>Deletes a job and its files.
Example
await rc.jobs.delete("job_01hx4k9m2p7w");Parameters
idstringThe job's ID.Required
Result files
Jobs.exportedFiles(job) → ResultFile[]The files produced by a finished job's export tasks: file name, a temporary download URL and size.
Example
import { Jobs } from "@runconvert/sdk";
for (const f of Jobs.exportedFiles(job)) console.log(f.filename, f.url);[
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]Parameters
jobJobA finished job, with its tasks.Required
Files
Upload a file
rc.files.upload(task, file, filename?) → Promise<void>Sends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.
Example
const upload = job.tasks!.find((t) => t.name === "upload")!;
await rc.files.upload(upload, "image.png");Parameters
taskTask | stringThe upload task from the created job, or its upload URL.Requiredfilestring | Uint8Array | Blob | ReadableStreamA local path, bytes, a Blob or a stream.RequiredfilenamestringThe file's name when you pass bytes or a stream.
Download a result
rc.files.download(file, dir, filename?) → Promise<string>Saves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory.
Example
for (const f of Jobs.exportedFiles(job)) {
console.log(await rc.files.download(f, "out"));
}out/report.pdfParameters
fileResultFile | stringA result file from a job's export task, or its URL.RequireddirstringThe folder to save into.RequiredfilenamestringSave under this name instead.
Returns
The saved file's path.
Formats
List formats
rc.operations.list({ category? }) → Promise<OperationsCatalog>Every input format and what it converts to. Public: no API key needed.
Example
const catalog = await rc.operations.list({ category: "audio" });
console.log(catalog.formats.length);Parameters
categoryCategoryOnly one category: document, image, video, audio, ebook, archive, font, cad, …
Returns
{ categories, formats }
Targets for a format
rc.operations.forInput(input) → Promise<InputFormat>What one format converts to, with the credit cost of each conversion. Public.
Example
const mp4 = await rc.operations.forInput("mp4");
for (const o of mp4.outputs) console.log(o.format, o.credits);{
"format": "mp4",
"category": "video",
"outputs": [
{ "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
{ "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
…
]
}Parameters
inputstringThe input format, e.g. "mp4".Required
Engines for a pair
rc.operations.forPair(input, output) → Promise<PairEngines>The engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.
Example
const pair = await rc.operations.forPair("mp4", "mp3");
for (const opt of pair.engines[0].options) console.log(opt.name);{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
inputstringThe input format, e.g. "mp4".RequiredoutputstringThe output format, e.g. "mp3".Required
Account
Credits and team
rc.me() → Promise<Me>The account, team and credit balance behind the API key.
Example
const me = await rc.me();
console.log(me.credits.total_remaining);{
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Verify a signature
verifySignature(rawBody, signature, secret) → booleanChecks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.
Example
import { verifySignature } from "@runconvert/sdk";
const ok = verifySignature(
req.body, // raw body
req.get("X-RunConvert-Signature"),
process.env.RUNCONVERT_WEBHOOK_SECRET!,
);Parameters
rawBodystring | Uint8ArrayThe raw request body, exactly as received (not parsed JSON).RequiredsignaturestringThe X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
Parse an event
constructEvent(rawBody, signature, secret) → WebhookEventVerifies the signature and parses the event in one step. Fails if the signature is wrong.
Throws when the signature doesn't match: answer 400 and ignore the request. Read the body raw (e.g. express.raw()), not as parsed JSON.
Example
import express from "express";
import { constructEvent } from "@runconvert/sdk";
app.post("/webhooks/runconvert", express.raw({ type: "application/json" }), (req, res) => {
let event;
try {
event = constructEvent(req.body, req.get("X-RunConvert-Signature"), process.env.RUNCONVERT_WEBHOOK_SECRET!);
} catch {
return res.sendStatus(400);
}
if (event.event === "job.finished") console.log("done", event.job.id);
res.sendStatus(200);
});{
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Parameters
rawBodystring | Uint8ArrayThe raw request body, exactly as received (not parsed JSON).RequiredsignaturestringThe X-RunConvert-Signature header.RequiredsecretstringYour webhook's signing secret.Required
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA.
Example
import { RunConvertError, JobFailedError } from "@runconvert/sdk";
try {
await rc.convert("report.docx", { to: "pdf", outDir: "out" });
} catch (e) {
if (e instanceof JobFailedError) console.log("conversion failed:", e.task?.reason);
else if (e instanceof RunConvertError) console.log(e.status, e.code, e.message);
else throw e;
}422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.Error types
RunConvertErrorclassThe API said no: .status (HTTP status), .code (e.g. BILLING_INSUFFICIENT_CREDITS), .message.JobFailedErrorclassThe job ended in error: .job, and .task with code, reason and message.WaitTimeoutErrorclasswait() ran past its timeout: .job is the job as last seen.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.
Example
const rc = new RunConvert({ maxRetries: 4, timeout: 30_000 });