The Job object

A job represents a video transcoding operation. Each job takes an input video and produces one or more output renditions based on your specifications. Jobs support real-time progress tracking, delayed start with cost review, and streaming updates.

Base path: transcodely.v1.JobService Requires: X-Organization-ID header on all endpoints.

Attributes

Attribute	Type	Description
`id`	string	Unique identifier. Prefixed with `job_`.
`object`	string	Resource type discriminator. Always `"job"`.
`app_id`	string	Parent app that owns the job. Prefixed with `app_`. Server-set.
`input_url`	string	Input video URL (when using direct URL mode).
`input_origin`	object \| null	Input origin reference (when using origin mode).
`output_origin`	object \| null	Output origin reference.
`status`	enum	Current job status. One of: `pending`, `probing`, `awaiting_confirmation`, `processing`, `completed`, `failed`, `canceled`, `partial`.
`progress`	integer	Overall progress percentage (0–100).
`priority`	enum	Job priority. One of: `economy`, `standard`, `premium`.
`input_metadata`	object \| null	Input file metadata, populated after probing. See Input Metadata.
`outputs`	array of objects	Output renditions. See The Output Object.
`thumbnails`	array of objects	Thumbnail specifications. See Thumbnails.
`thumbnail_results`	array of objects	Generated thumbnail artifacts (`url`, `signed_url`, `mode`, `index`), populated after the job completes.
`subtitle_results`	array of objects	Produced subtitle artifacts, one per subtitle track. Generated tracks additionally expose a segment-level transcript. See Subtitles.
`chapter_results`	array of objects	Auto-generated chapter tracks, one per output whose generated caption track had `generate_chapters` enabled. Empty otherwise.
`input_video_id`	string	Hosted video used as the input source, echoed from the request. Empty when the job was created with `input_url` or an input origin. Prefixed with `vid_`.
`total_estimated_cost`	number	Estimated cost in EUR. Present after probe completes.
`total_actual_cost`	number	Actual cost in EUR. Present after outputs complete.
`minimum_charge_eur`	number	Deprecated, historical jobs only. The per-job minimum charge locked at creation, for jobs created before the processing-fee model (August 2026). Absent on jobs created since. See Processing fee.
`minimum_charge_applied`	boolean	Deprecated, historical jobs only. `true` when the minimum exceeded the summed output costs and set the job’s total. Always `false` on jobs created under the processing-fee model.
`fees`	array of objects	Additive fees billed on top of the encoding cost. Every job an encoder starts carries a `processing` fee (`unit` `job`, `quantity` 1) — see Processing fee; metered add-ons such as AI captions appear here too. Each carries `id`, `fee_type`, `description`, `unit`, `quantity`, `rate`, `amount`, `currency`. Voided fees are omitted.
`cost_breakdown`	object \| null	Itemized decomposition of both totals, whose lines sum to them. See The cost breakdown. Server-set.
`error_code`	string	Error code if failed. Branch on this, not on `error_message`.
`error_message`	string	Human-readable summary of the failure, derived from `error_code`. Never raw transcoder output, and not a stable string to match on.
`webhook_url`	string	Legacy per-job webhook URL. Use webhook endpoints for signed event delivery.
`metadata`	object	Custom key-value metadata.
`output_path_template`	string \| null	Job-level output path template echoed from the request. `null` when not specified.
`clip`	object \| null	Clip range echoed from the request (`start_seconds`, `end_seconds`). `null` when the full input is encoded. See Clipping and trimming.
`video_id`	string \| null	Hosted video this job’s managed output belongs to. Prefixed with `vid_`. Set for managed jobs (`managed: true` or `input_video_id`); `null` for jobs delivering to your own origin. Server-set.
`delayed_start`	boolean	Whether this job requires confirmation before encoding.
`currency`	string	Currency for cost fields (e.g., `EUR`).
`execution`	object \| null	Execution timing and telemetry. See Execution Timing.
`created_at`	string	ISO 8601 timestamp.
`updated_at`	string	ISO 8601 timestamp.
`probed_at`	string \| null	When probing completed.
`started_at`	string \| null	When processing started.
`completed_at`	string \| null	When job reached terminal state.
`confirmed_at`	string \| null	When delayed start job was confirmed.

{
  "id": "job_a1b2c3d4e5f6",
  "object": "job",
  "app_id": "app_k1l2m3n4o5",
  "input_url": "gs://my-bucket/uploads/video.mp4",
  "input_origin": null,
  "output_origin": {
    "id": "ori_x9y8z7w6v5",
    "name": "Production GCS Bucket",
    "provider": "gcs",
    "path": "",
    "bucket": "acme-video-assets"
  },
  "status": "completed",
  "progress": 100,
  "priority": "standard",
  "input_metadata": {
    "format": "mp4",
    "duration_ms": 125000,
    "size_bytes": 132710400,
    "bit_rate": 8500000,
    "video": {
      "codec": "h264",
      "width": 1920,
      "height": 1080,
      "frame_rate": 30,
      "bit_rate": 8000000,
      "pixel_format": "yuv420p"
    },
    "audio": {
      "codec": "aac",
      "sample_rate": 48000,
      "channels": 2,
      "channel_layout": "stereo",
      "bit_rate": 128000
    }
  },
  "outputs": [
    {
      "id": "out_m1n2o3p4q5",
      "spec": {
        "type": "mp4",
        "video": [
          {
            "codec": "h264",
            "resolution": "1080p",
            "quality": "standard"
          }
        ]
      },
      "status": "completed",
      "progress": 100,
      "output_url": "gs://acme-video-assets/2025/02/28/output_h264_1080p.mp4",
      "output_size_bytes": 67108864
    }
  ],
  "total_estimated_cost": 0.90,
  "total_actual_cost": 0.87,
  "fees": [
    {
      "id": "fee_a1b2c3d4e5f6",
      "fee_type": "processing",
      "description": "Processing fee",
      "unit": "job",
      "quantity": 1,
      "rate": 0.05,
      "amount": 0.05,
      "currency": "eur"
    }
  ],
  "cost_breakdown": {
    "lines": [
      {
        "type": "output",
        "reference_id": "out_m1n2o3p4q5",
        "description": "1080p h264 mp4",
        "estimated_amount_eur": 0.85,
        "actual_amount_eur": 0.82
      },
      {
        "type": "fee",
        "reference_id": "fee_a1b2c3d4e5f6",
        "description": "Processing fee",
        "estimated_amount_eur": 0.05,
        "actual_amount_eur": 0.05
      }
    ],
    "total_estimated_cost": 0.90,
    "total_actual_cost": 0.87
  },
  "error_code": "",
  "error_message": "",
  "metadata": {
    "source": "upload-service",
    "user_id": "usr_a1b2c3d4e5"
  },
  "clip": {
    "start_seconds": 2,
    "end_seconds": 7
  },
  "delayed_start": false,
  "currency": "EUR",
  "execution": {
    "probe_duration_ms": 1200,
    "encode_duration_ms": 45000,
    "total_duration_ms": 46200
  },
  "created_at": "2025-02-28T10:00:00Z",
  "updated_at": "2025-02-28T10:01:30Z",
  "probed_at": "2025-02-28T10:00:02Z",
  "started_at": "2025-02-28T10:00:03Z",
  "completed_at": "2025-02-28T10:01:30Z",
  "confirmed_at": null
}

Statuses

Status	Description
`pending`	Queued and waiting to be processed.
`probing`	Analyzing the input file.
`awaiting_confirmation`	Delayed start job paused for cost review. Call Confirm to proceed.
`processing`	Actively transcoding.
`completed`	All outputs completed successfully.
`failed`	Job failed with an error.
`canceled`	Canceled by the user.
`partial`	Some outputs completed, others failed.

The cost breakdown

cost_breakdown itemizes both of the job’s totals, so a bill can be read rather than trusted. Its lines carry the same two sides the job does — estimated_amount_eur and actual_amount_eur — and each side sums to the matching total. That is a guarantee, not a convention: anything the itemized lines do not account for is carried on a signed adjustment line rather than being quietly dropped.

Field	Type	Description
`lines`	array of objects	The charges, in reading order: outputs, then fees (the processing fee among them), then the minimum charge on historical jobs, then any adjustment.
`total_estimated_cost`	number \| null	Same value as the job’s `total_estimated_cost`, repeated so a breakdown verifies on its own.
`total_actual_cost`	number \| null	Same value as the job’s `total_actual_cost`.

Cost breakdown lines

Field	Type	Description
`type`	enum	`output`, `minimum_charge`, `fee` or `adjustment`.
`reference_id`	string	The output (`out_`) or fee (`fee_`) the line is for — including the processing fee, which is a `fee_` like any other. Empty on `minimum_charge` and `adjustment`, which belong to the job as a whole.
`description`	string	Human-readable label. Documentation, not API surface — branch on `type` and `reference_id`, never on this wording.
`estimated_amount_eur`	number \| null	What the line contributed to the estimate. Absent until the input probe supplies a duration.
`actual_amount_eur`	number \| null	What the line contributed to the settled total. Absent until the job settles; `0` for a line that settled at no charge. Absent and zero are different answers — one is “not known yet”, the other is “free”. Negative only on an `adjustment` line.

Line types:

Type	Meaning
`output`	One output rendition’s share of the total.
`minimum_charge`	Historical jobs only. What the retired per-job minimum added on top of the renditions. Present when the minimum raised either total; a side it did not raise reads `0`. Never appears on a job created under the processing-fee model.
`fee`	One additive fee — the per-job processing fee, or a metered add-on. Fee lines cover every fee quoted on the job, including fees later voided — those settle at `0`. (The job’s `fees` array omits voided fees: it answers “what am I charged for”, while the breakdown answers “how is this number composed”.)
`adjustment`	A signed reconciliation difference between the itemized lines and the stored total — metering refined between the estimate and settlement, for instance. Rare by design, and may be negative.

What the actual side contains follows the job’s outcome, matching what is billed: a completed or partial job’s total is its processing fee plus the outputs it delivered; a job canceled after an encoder picked it up is the same, over however many outputs finished first; a job canceled while still queued and a failed job bill nothing at all — every line settles at 0, the processing fee included.

Priorities

Priority affects worker selection and scheduling order only — it has no effect on cost. Pricing is driven by codec, resolution, framerate, and quality tier (see the quality field on each video variant).

Priority	Description
`economy`	Smaller workers, slower encoding.
`standard`	Balanced worker sizing and scheduling. Default.
`premium`	Largest workers and highest scheduling priority for the fastest encoding.

Create a job

Create a new transcoding job with one or more output renditions.

POST /transcodely.v1.JobService/Create

Parameters

Parameter	Type	Required	Description
`input_url`	string	One of	Direct URL to the input video. Supported schemes: `gs://`, `s3://`, `https://`. Use this or `input_origin_id`, not both.
`input_origin_id`	string	One of	Origin ID for the input source. The origin must have read permission.
`input_path`	string	No	Path within the input origin. Required when using `input_origin_id`.
`output_origin_id`	string	Conditional	Origin ID for outputs. Must have write permission. Required unless `managed` is `true`.
`outputs`	array	Yes	Output specifications (1–10 outputs). See Output Specification.
`priority`	enum	No	`economy`, `standard`, or `premium`. Default: `standard`.
`thumbnails`	array	No	Thumbnail specifications (max 5). See Thumbnails.
`webhook_url`	string	No	Legacy per-job webhook URL. Register a webhook endpoint for signed event delivery instead.
`idempotency_key`	string	No	Idempotency key (max 128 chars). Duplicate requests return the existing job.
`metadata`	object	No	Custom key-value pairs (max 20 entries, keys max 64 chars, values max 1024 chars).
`delayed_start`	boolean	No	If `true`, pauses after probing for cost review. Default: `false`.
`output_path_template`	string	No	Output path template. Variables: `{job_id}`, `{output_id}`, `{date}`, `{format}`, `{codec}`, `{resolution}`, `{quality}`.
`clip`	object	No	Encode only a sub-range of the input: `{ "start_seconds": 2, "end_seconds": 7 }`. `start_seconds` defaults to `0`; omit `end_seconds` (or set `0`) to encode to the end of the input. Applies job-wide. See Clipping and trimming.
`managed`	boolean	No	Write outputs to managed hosting storage and create a video record. When `true`, `output_origin_id` is not required. Default: `false`.
`app_id`	string	No	Target app (`app_` prefix). API-key callers may omit it (their key’s app is used); portal/JWT callers pass it to create in a specific app, or omit to select the org’s first active app.

Output specification

Each output can be defined inline or reference a preset. For the full reference of all output fields, see Output Specification.

Field	Type	Required	Description
`type`	enum	Yes*	`mp4`, `webm`, `mkv`, `mov`, `hls`, `dash`, or `adaptive`. *Required unless using `preset`.
`video`	array	Yes*	Video variants (1–20). *Required unless using `preset`.
`audio`	array	No	Audio tracks for streaming outputs. Max 8 tracks.
`hls`	object	No	HLS-specific configuration.
`dash`	object	No	DASH-specific configuration.
`segments`	object	No	Segment configuration for streaming types.
`path_template`	string	No	Per-output path template (overrides job-level template).
`preset`	string	No	Preset ID (e.g., `pst_abc123`) or slug (e.g., `web_1080p_standard`).
`subtitle_tracks`	array	No	Subtitle track configuration (max 8). See Subtitles.
`drm`	object	No	DRM encryption configuration. Streaming outputs only. See DRM & Encryption.
`content_aware`	object	No	Content-aware encoding. See Content-Aware Encoding.
`encoding_mode`	string	No	`"fixed"` (default, static CRF) or `"auto"` (input-aware constrained CRF that caps each variant’s bitrate to the input’s quality ceiling).
`disable_audio`	boolean	No	Produce a video-only output, dropping audio entirely. Cannot be combined with `audio[]` tracks.
`effective_path_template`	string	Read-only	Resolved path template the worker renders against, after composing job-level and per-output templates. Response-only; ignored on requests.

VideoVariant

Each variant defines a single video encode rendition. For the full reference including codec-specific options (H264Options, H265Options, VP9Options, AV1Options) and HDR configuration, see Video Variants.

Field	Type	Required	Description
`codec`	enum	Yes	`h264`, `h265`, `vp9`, or `av1`.
`resolution`	enum	No	`480p`, `720p`, `1080p`, `1440p`, `2160p`, or `4320p`.
`quality`	enum	No	`economy`, `standard`, or `premium`.
`framerate`	integer	No	Target frame rate. 0 = keep original.
`width`	integer	No	Custom width in pixels (128–7680).
`height`	integer	No	Custom height in pixels (128–4320).
`bitrate`	integer	No	Target bitrate in kbps (100–240000).
`h264`	object	No	H.264-specific options.
`h265`	object	No	H.265-specific options.
`vp9`	object	No	VP9-specific options.
`av1`	object	No	AV1-specific options.
`hdr`	object	No	HDR configuration.

Returns

Returns a Job object.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "output_origin_id": "ori_x9y8z7w6v5",
    "outputs": [
      {
        "type": "mp4",
        "video": [
          {"codec": "h264", "resolution": "1080p", "quality": "standard"}
        ]
      }
    ],
    "priority": "standard"
  }'

const job = await client.jobs.create({
  inputUrl: "gs://my-bucket/uploads/video.mp4",
  outputOriginId: "ori_x9y8z7w6v5",
  outputs: [
    {
      type: OutputFormat.MP4,
      video: [
        {
          codec: VideoCodec.H264,
          resolution: Resolution.RESOLUTION_1080P,
          quality: QualityTier.STANDARD,
        },
      ],
    },
  ],
  priority: JobPriority.STANDARD,
});

job = client.jobs.create(
    input_url="gs://my-bucket/uploads/video.mp4",
    output_origin_id="ori_x9y8z7w6v5",
    outputs=[{
        "type": "mp4",
        "video": [{"codec": "h264", "resolution": "1080p", "quality": "standard"}],
    }],
    priority="standard",
)

job, err := client.Jobs.Create(ctx, &transcodely.JobCreateParams{
    InputUrl:       "gs://my-bucket/uploads/video.mp4",
    OutputOriginId: proto.String("ori_x9y8z7w6v5"),
    Outputs: []*transcodely.OutputSpec{{
        Type: transcodely.OutputFormatMP4,
        Video: []*transcodely.VideoVariant{{
            Codec:      transcodely.VideoCodecH264,
            Resolution: transcodely.Resolution1080P,
            Quality:    transcodely.QualityTierStandard,
        }},
    }},
    Priority: transcodely.JobPriorityStandard,
})

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "input_origin": null,
    "output_origin": {
      "id": "ori_x9y8z7w6v5",
      "name": "Production GCS Bucket",
      "provider": "gcs",
      "path": "",
      "bucket": "acme-video-assets"
    },
    "status": "pending",
    "progress": 0,
    "priority": "standard",
    "input_metadata": null,
    "outputs": [],
    "metadata": {},
    "delayed_start": false,
    "currency": "EUR",
    "execution": null,
    "created_at": "2025-02-28T10:00:00Z",
    "updated_at": "2025-02-28T10:00:00Z"
  }
}

When managed is true, the response also includes a top-level video_id — the ID of the created managed-hosting video record. It is omitted for origin-based jobs.

Example: Adaptive streaming job

Package an HLS adaptive bitrate ladder — three H.264 renditions from 1080p down to 480p — in a single job.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "output_origin_id": "ori_x9y8z7w6v5",
    "outputs": [
      {
        "type": "hls",
        "video": [
          {"codec": "h264", "resolution": "1080p", "quality": "standard"},
          {"codec": "h264", "resolution": "720p", "quality": "standard"},
          {"codec": "h264", "resolution": "480p", "quality": "standard"}
        ],
        "segments": {"duration": 6}
      }
    ]
  }'

const job = await client.jobs.create({
  inputUrl: "gs://my-bucket/uploads/video.mp4",
  outputOriginId: "ori_x9y8z7w6v5",
  outputs: [
    {
      type: OutputFormat.HLS,
      video: [
        { codec: VideoCodec.H264, resolution: Resolution.RESOLUTION_1080P, quality: QualityTier.STANDARD },
        { codec: VideoCodec.H264, resolution: Resolution.RESOLUTION_720P, quality: QualityTier.STANDARD },
        { codec: VideoCodec.H264, resolution: Resolution.RESOLUTION_480P, quality: QualityTier.STANDARD },
      ],
      segments: { duration: 6 },
    },
  ],
});

job = client.jobs.create(
    input_url="gs://my-bucket/uploads/video.mp4",
    output_origin_id="ori_x9y8z7w6v5",
    outputs=[{
        "type": "hls",
        "video": [
            {"codec": "h264", "resolution": "1080p", "quality": "standard"},
            {"codec": "h264", "resolution": "720p", "quality": "standard"},
            {"codec": "h264", "resolution": "480p", "quality": "standard"},
        ],
        "segments": {"duration": 6},
    }],
)

job, err := client.Jobs.Create(ctx, &transcodely.JobCreateParams{
    InputUrl:       "gs://my-bucket/uploads/video.mp4",
    OutputOriginId: proto.String("ori_x9y8z7w6v5"),
    Outputs: []*transcodely.OutputSpec{{
        Type: transcodely.OutputFormatHLS,
        Video: []*transcodely.VideoVariant{
            {Codec: transcodely.VideoCodecH264, Resolution: transcodely.Resolution1080P, Quality: transcodely.QualityTierStandard},
            {Codec: transcodely.VideoCodecH264, Resolution: transcodely.Resolution720P, Quality: transcodely.QualityTierStandard},
            {Codec: transcodely.VideoCodecH264, Resolution: transcodely.Resolution480P, Quality: transcodely.QualityTierStandard},
        },
        Segments: &transcodely.SegmentConfig{Duration: proto.Int32(6)},
    }},
})

Retrieve a job

Retrieve a job by its ID.

POST /transcodely.v1.JobService/Get

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Job ID (e.g., `job_a1b2c3d4e5f6`).

Returns

Returns a Job object.

Get also mints signed, expiring HTTPS URLs for what the job produced — outputs[].signed_url, thumbnail_results[].signed_url, subtitle_results[].signed_url — for jobs written to Transcodely-managed storage. List never does. See Signed asset URLs.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Get 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"id": "job_a1b2c3d4e5f6"}'

const job = await client.jobs.get("job_a1b2c3d4e5f6");

job = client.jobs.get(id="job_a1b2c3d4e5f6")

job, err := client.Jobs.Get(ctx, "job_a1b2c3d4e5f6")

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "object": "job",
    "app_id": "app_k1l2m3n4o5",
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "input_origin": null,
    "output_origin": {
      "id": "ori_x9y8z7w6v5",
      "name": "Production GCS Bucket",
      "provider": "gcs",
      "path": "",
      "bucket": "acme-video-assets"
    },
    "status": "completed",
    "progress": 100,
    "priority": "standard",
    "input_metadata": {
      "format": "mp4",
      "duration_ms": 125000,
      "size_bytes": 132710400,
      "bit_rate": 8500000,
      "video": {
        "codec": "h264",
        "width": 1920,
        "height": 1080,
        "frame_rate": 30,
        "bit_rate": 8000000,
        "pixel_format": "yuv420p"
      },
      "audio": {
        "codec": "aac",
        "sample_rate": 48000,
        "channels": 2,
        "channel_layout": "stereo",
        "bit_rate": 128000
      }
    },
    "outputs": [
      {
        "id": "out_m1n2o3p4q5",
        "spec": {
          "type": "mp4",
          "video": [
            {
              "codec": "h264",
              "resolution": "1080p",
              "quality": "standard"
            }
          ]
        },
        "status": "completed",
        "progress": 100,
        "output_url": "gs://acme-video-assets/2025/02/28/output_h264_1080p.mp4",
        "output_size_bytes": 67108864
      }
    ],
    "total_estimated_cost": 0.90,
    "total_actual_cost": 0.87,
    "fees": [
      {
        "id": "fee_a1b2c3d4e5f6",
        "fee_type": "processing",
        "description": "Processing fee",
        "unit": "job",
        "quantity": 1,
        "rate": 0.05,
        "amount": 0.05,
        "currency": "eur"
      }
    ],
    "cost_breakdown": {
      "lines": [
        {
          "type": "output",
          "reference_id": "out_m1n2o3p4q5",
          "description": "1080p h264 mp4",
          "estimated_amount_eur": 0.85,
          "actual_amount_eur": 0.82
        },
        {
          "type": "fee",
          "reference_id": "fee_a1b2c3d4e5f6",
          "description": "Processing fee",
          "estimated_amount_eur": 0.05,
          "actual_amount_eur": 0.05
        }
      ],
      "total_estimated_cost": 0.90,
      "total_actual_cost": 0.87
    },
    "error_code": "",
    "error_message": "",
    "metadata": {
      "source": "upload-service",
      "user_id": "usr_a1b2c3d4e5"
    },
    "delayed_start": false,
    "currency": "EUR",
    "execution": {
      "probe_duration_ms": 1200,
      "encode_duration_ms": 45000,
      "total_duration_ms": 46200
    },
    "created_at": "2025-02-28T10:00:00Z",
    "updated_at": "2025-02-28T10:01:30Z",
    "probed_at": "2025-02-28T10:00:02Z",
    "started_at": "2025-02-28T10:00:03Z",
    "completed_at": "2025-02-28T10:01:30Z",
    "confirmed_at": null
  }
}

List jobs

List jobs with optional status filtering and pagination.

POST /transcodely.v1.JobService/List

Parameters

Parameter	Type	Required	Description
`status`	enum	No	Filter by status: `pending`, `probing`, `processing`, `completed`, `failed`, `canceled`, `partial`, `awaiting_confirmation`.
`pagination`	object	No	`limit` (default 20, max 100), plus `cursor` or `offset` (alternatives) for paging.
`app_id`	string	No	Filter to a specific app (`app_` prefix). API-key callers may omit it (their key’s app is used); portal/JWT callers pass it to list a specific app, or omit to return jobs across all apps in the org.

Returns

Returns a list of Job objects and pagination metadata. Listed jobs carry no signed asset URLs; read a job with Get when you need one.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/List 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"status": "processing", "pagination": {"limit": 20}}'

const { items, nextCursor } = await client.jobs.list({
  status: JobStatus.PROCESSING,
  pagination: { limit: 20 },
});

response = client.jobs.list(status="processing", pagination={"limit": 20})

status := transcodely.JobStatusProcessing
iter := client.Jobs.List(ctx, &transcodely.JobListParams{
    Status:     &status,
    Pagination: &transcodely.PaginationRequest{Limit: 20},
})
defer iter.Close()

for iter.Next() {
    job := iter.Current()
    fmt.Printf("%s %s\n", job.GetId(), job.GetStatus())
}
if err := iter.Err(); err != nil {
    log.Fatal(err)
}

{
  "jobs": [
    {
      "id": "job_a1b2c3d4e5f6",
      "input_url": "gs://my-bucket/uploads/video.mp4",
      "status": "processing",
      "progress": 45,
      "priority": "standard",
      "created_at": "2025-02-28T10:00:00Z",
      "updated_at": "2025-02-28T10:02:00Z"
    },
    {
      "id": "job_b2c3d4e5f6g7",
      "input_url": "gs://my-bucket/uploads/interview.mov",
      "status": "processing",
      "progress": 78,
      "priority": "premium",
      "created_at": "2025-02-28T09:45:00Z",
      "updated_at": "2025-02-28T10:02:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6ImpvYl9iMmMzZDRlNWY2ZzcifQ",
    "total_count": 42
  }
}

Cancel a job

Cancel a pending or running job. Completed outputs are preserved, in-progress outputs are stopped.

POST /transcodely.v1.JobService/Cancel

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Job ID.

Returns

Returns the Job object with status: "canceled".

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Cancel 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"id": "job_a1b2c3d4e5f6"}'

const job = await client.jobs.cancel("job_a1b2c3d4e5f6");

job = client.jobs.cancel(id="job_a1b2c3d4e5f6")

job, err := client.Jobs.Cancel(ctx, "job_a1b2c3d4e5f6")

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "status": "canceled",
    "progress": 45,
    "priority": "standard",
    "created_at": "2025-02-28T10:00:00Z",
    "updated_at": "2025-02-28T10:05:00Z",
    "completed_at": "2025-02-28T10:05:00Z"
  }
}

Confirm a job

Confirm a delayed start job to begin encoding. Only valid when the job is in awaiting_confirmation status.

POST /transcodely.v1.JobService/Confirm

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Job ID.

Returns

Returns the Job object with status transitioning to processing.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Confirm 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"id": "job_a1b2c3d4e5f6"}'

const job = await client.jobs.confirm("job_a1b2c3d4e5f6");

job = client.jobs.confirm(id="job_a1b2c3d4e5f6")

job, err := client.Jobs.Confirm(ctx, "job_a1b2c3d4e5f6")

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "input_url": "gs://my-bucket/uploads/video.mp4",
    "status": "processing",
    "progress": 0,
    "priority": "standard",
    "delayed_start": true,
    "created_at": "2025-02-28T10:00:00Z",
    "updated_at": "2025-02-28T10:05:00Z",
    "confirmed_at": "2025-02-28T10:05:00Z"
  }
}

Watch a job

Stream real-time updates for a job. The server sends the current state immediately, then pushes updates as status or progress changes. The stream closes when the job reaches a terminal state.

This is a server-streaming RPC.

POST /transcodely.v1.JobService/Watch

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Job ID.

Stream events

Each message in the stream contains the current Job object, an event type, and a server timestamp.

Event	Description
`snapshot`	Initial state sent on connection.
`progress`	Progress percentage changed (debounced 200ms).
`status_change`	Job status transitioned.
`completed`	Terminal state reached. Stream closes after this.
`heartbeat`	Keepalive every 3 seconds.

Returns

Newline-delimited JSON stream of job state updates.

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Watch 
  -H "Authorization: Bearer ak_abc123" 
  -H "X-Organization-ID: org_f6g7h8i9j0" 
  -H "Content-Type: application/json" 
  -d '{"id": "job_a1b2c3d4e5f6"}'

for await (const event of client.jobs.watch("job_a1b2c3d4e5f6")) {
  console.log(`${event.event}: ${event.job?.progress}%`);
  if (event.event === WatchEventType.COMPLETED) break;
}

from transcodely import WatchEventType

for event in client.jobs.watch(id="job_a1b2c3d4e5f6"):
    print(f"{WatchEventType.Name(event.event)}: {event.job.progress}%")
    if event.event == WatchEventType.WATCH_EVENT_TYPE_COMPLETED:
        break

stream := client.Jobs.Watch(ctx, "job_a1b2c3d4e5f6")
defer stream.Close()
for stream.Next() {
    event := stream.Current()
    fmt.Printf("%s: %d%%\n", event.GetEvent(), event.GetJob().GetProgress())
    if event.GetEvent() == transcodely.WatchEventCompleted {
        break
    }
}
if err := stream.Err(); err != nil {
    log.Fatal(err)
}

{"result": {"job": {"id": "job_a1b2c3d4e5f6", "status": "processing", "progress": 45}, "event": "snapshot", "server_time": "2025-02-28T10:05:00Z"}}
{"result": {"job": {"id": "job_a1b2c3d4e5f6", "status": "processing", "progress": 85}, "event": "progress", "server_time": "2025-02-28T10:05:30Z"}}
{"result": {"job": {"id": "job_a1b2c3d4e5f6", "status": "completed", "progress": 100}, "event": "completed", "server_time": "2025-02-28T10:05:45Z"}}

#The Job object

#Attributes

#Statuses

#The cost breakdown

#Cost breakdown lines

#Priorities

#Create a job

#Parameters

#Output specification

#VideoVariant

#Returns

#Example: Adaptive streaming job

#Retrieve a job

#Parameters

#Returns

#List jobs

#Parameters

#Returns

#Cancel a job

#Parameters

#Returns

#Confirm a job

#Parameters

#Returns

#Watch a job

#Parameters

#Stream events

#Returns

The Job object

Attributes

Statuses

The cost breakdown

Cost breakdown lines

Priorities

Create a job

Parameters

Output specification

VideoVariant

Returns

Example: Adaptive streaming job

Retrieve a job

Parameters

Returns

List jobs

Parameters

Returns

Cancel a job

Parameters

Returns

Confirm a job

Parameters

Returns

Watch a job

Parameters

Stream events

Returns