SDK

Jobs

A job is one extraction run on one source video. lirovo.jobs exposes create, list, get, getResult, and waitForResult.

jobs.create(input)#

Submits a job and resolves to a Job. Input is a CreateJobInput. Pass at most one of schemaId or schemaInline: they are mutually exclusive, and providing both throws locally before any request is sent.

sourceUrirequired

string

The source video URI. Sent on the wire as source_uri.

schemaId

string | null

Reference to a previously created schema. Mutually exclusive with schemaInline. Sent as schema_id.

schemaInline

Record<string, unknown> | null

An inline JSON Schema for this job only. Mutually exclusive with schemaId. Sent as schema_inline.

destinationIds

string[]

Destination ids to push the result to. Sent as destination_ids.

webhookUrl

string | null

A one-off webhook URL for this job. Sent as webhook_url.

const job = await lirovo.jobs.create({
  sourceUri: "https://youtube.com/watch?v=...",
  schemaId: "sch_a1b2",
  destinationIds: ["dst_9f3c"],
});
// => Job { id, status, ... }

schemaId and schemaInline are mutually exclusive

Passing both schemaId and schemaInline throws an Error locally (no request is sent), matching the server-side CONFLICTING_SCHEMA_REF.

jobs.list(params?)#

Lists jobs and resolves to a JobList. Accepts an optional status filter plus limit and cursor for pagination.

const page = await lirovo.jobs.list({ status: "succeeded", limit: 20 });
// => JobList { data, ... }

jobs.get(id)#

Fetches a single job by id and resolves to a Job. Read job.status to track progress (queued, running, succeeded, failed, cancelled).

const job = await lirovo.jobs.get("job_7k2p");

jobs.getResult(id)#

Fetches the typed extraction for a job and resolves to a JobResult. Call this once the job has succeeded, or let waitForResult do it for you.

const result = await lirovo.jobs.getResult("job_7k2p");

jobs.waitForResult(id, options?)#

Polls jobs.get(id) until the job reaches a terminal state, then fetches and returns the typed JobResult. The polling uses exponential backoff: it starts at initialIntervalMs (default 1 second), doubles after each attempt, and caps at maxIntervalMs (default 5 seconds). It gives up after timeoutMs total wall time (default 5 minutes). Options are a WaitForResultOptions.

timeoutMs

number

Total wait budget in milliseconds. Default: 5 minutes (300_000).

initialIntervalMs

number

Initial poll delay in milliseconds. Each poll then doubles up to maxIntervalMs. Default: 1_000.

maxIntervalMs

number

Cap on the polling interval, in milliseconds. Default: 5_000.

signal

AbortSignal

Optional abort signal. When it fires, the call rejects with an AbortError.

const result = await lirovo.jobs.waitForResult(job.id, {
  timeoutMs: 10 * 60 * 1000, // 10 minutes
  initialIntervalMs: 1_000,
  maxIntervalMs: 5_000,
});

Terminal failures vs. client timeout

If the job ends in failed or cancelled, waitForResult throws a LirovoApiError carrying the job's error code and message. If the wall-time budget runs out before the job reaches succeeded, it throws a LirovoApiError with code SDK_POLL_TIMEOUT. That code is SDK-only and distinct from the server-side UPSTREAM_TIMEOUT, so you can tell "the SDK gave up polling" apart from "the API timed out upstream". See Errors for the thrown shape.