First Job — Transcodely Docs

Your First Job

This guide walks through the complete lifecycle of a transcoding job — from submission to completion. You will learn how to configure outputs, monitor progress in real time, and handle the results.

Job Lifecycle

Every job progresses through a series of statuses:

Status	Description
`pending`	Job is queued and waiting to be assigned to a worker
`probing`	Worker is analyzing the input file with ffprobe
`awaiting_confirmation`	Delayed-start job waiting for cost review (optional)
`processing`	Actively encoding the video
`completed`	All outputs finished successfully
`partial`	Some outputs completed, others failed
`failed`	Job failed with an error
`canceled`	Job was canceled by the user

Creating a Job

A job requires an input source and at least one output specification. You can configure outputs inline or reference a saved preset:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "input_url": "https://storage.example.com/uploads/interview.mp4",
    "output_origin_id": "ori_x9y8z7w6v5",
    "outputs": [
      {
        "type": "mp4",
        "video": [
          {
            "codec": "h264",
            "resolution": "1080p",
            "quality": "standard"
          }
        ]
      },
      {
        "type": "webm",
        "video": [
          {
            "codec": "vp9",
            "resolution": "720p",
            "quality": "economy"
          }
        ]
      }
    ],
    "priority": "standard",
    "webhook_url": "https://myapp.com/webhooks/transcode",
    "metadata": {
      "user_id": "usr_12345",
      "project": "marketing-videos"
    }
  }'

This creates a job with two outputs: a 1080p H.264 MP4 and a 720p VP9 WebM. The metadata fields are stored with the job and returned in all responses and webhook payloads.

Using Presets

Instead of configuring every parameter inline, reference a preset by ID or slug:

curl -X POST https://api.transcodely.com/transcodely.v1.JobService/Create 
  -H "Authorization: Bearer {{API_KEY}}" 
  -H "Content-Type: application/json" 
  -d '{
    "input_url": "https://storage.example.com/uploads/interview.mp4",
    "output_origin_id": "ori_x9y8z7w6v5",
    "outputs": [
      {"preset": "pst_x9y8z7w6v5"},
      {"preset": "web_720p_standard"}
    ],
    "priority": "standard"
  }'

Monitoring Progress

Polling

Retrieve the current job state at any time:

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

The response includes per-output progress:

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "status": "processing",
    "progress": 45,
    "outputs": [
      {
        "id": "out_g7h8i9j0k1",
        "status": "processing",
        "progress": 72
      },
      {
        "id": "out_l2m3n4o5p6",
        "status": "pending",
        "progress": 0
      }
    ]
  }
}

Real-Time Watch Stream

For live progress updates, use the Watch RPC. It returns the current state immediately, then streams updates as the job progresses:

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

Each message includes an event type:

Event	Description
`snapshot`	Initial state when the stream opens
`progress`	Progress percentage changed
`status_change`	Job or output transitioned to a new status
`completed`	Job reached a terminal state (stream closes after this)
`heartbeat`	Keepalive sent every 30 seconds

Delayed Start Jobs

If you want to review the estimated cost before encoding begins, set delayed_start to true:

{
  "input_url": "https://storage.example.com/uploads/long-video.mp4",
  "output_origin_id": "ori_x9y8z7w6v5",
  "outputs": [{"type": "mp4", "video": [{"codec": "h264", "resolution": "2160p", "quality": "premium"}]}],
  "delayed_start": true
}

After probing, the job enters awaiting_confirmation with a cost estimate. Call Confirm to proceed:

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

Canceling a Job

Cancel a pending or in-progress job at any time:

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

For jobs that are already encoding, you are billed only for the portion that was completed before cancellation.

Completed Job Response

When all outputs finish, the job includes output URLs, file sizes, durations, and costs:

{
  "job": {
    "id": "job_a1b2c3d4e5f6",
    "status": "completed",
    "progress": 100,
    "total_estimated_cost": 0.092,
    "total_actual_cost": 0.089,
    "currency": "EUR",
    "outputs": [
      {
        "id": "out_g7h8i9j0k1",
        "status": "completed",
        "output_url": "gs://my-bucket/job_a1b2c3d4e5f6/out_g7h8i9j0k1.mp4",
        "output_size_bytes": 15728640,
        "duration_seconds": 120,
        "estimated_cost": 0.052,
        "actual_cost": 0.050
      },
      {
        "id": "out_l2m3n4o5p6",
        "status": "completed",
        "output_url": "gs://my-bucket/job_a1b2c3d4e5f6/out_l2m3n4o5p6.webm",
        "output_size_bytes": 8912340,
        "duration_seconds": 120,
        "estimated_cost": 0.040,
        "actual_cost": 0.039
      }
    ]
  }
}

Next Steps

SDKs — Use an official SDK instead of raw HTTP
Encoding — Learn about codecs, quality tiers, and advanced options
Webhooks — Get notified when jobs complete instead of polling

#Your First Job

#Job Lifecycle

#Creating a Job

#Using Presets

#Monitoring Progress

#Polling

#Real-Time Watch Stream

#Delayed Start Jobs

#Canceling a Job

#Completed Job Response

#Next Steps