Ittybit

Introduction

A run is a workflow execution that contains one or more tasks. Runs let you chain tasks together, run them in parallel, or add conditional logic — all in a single API call.

Every task belongs to a run. When you use POST /tasks to create a single task, a run is automatically created behind the scenes.

Creating a run

Create a run by sending a POST request to /runs with a tasks array:

curl -X POST "https://api.ittybit.com/runs" \
-H "Authorization: Bearer ITTYBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "tasks": [
    {
      "kind": "ingest",
      "options": {
        "url": "https://example.com/video.mp4"
      }
    },
    {
      "kind": "video",
      "options": {
        "width": 1280,
        "height": 720,
        "format": "mp4"
      }
    },
    {
      "kind": "speech"
    },
    {
      "kind": "summary"
    }
  ]
}'

This run will ingest the video, then create a 720p version, transcribe it, and generate a summary — all as part of a single workflow.

Run object

{
  "id": "run_abcdefgh12345678",
  "object": "run",
  "status": "processing",
  "progress": 50,
  "metadata": {},
  "error": null,
  "created_by": "key_abcdefgh12345678",
  "created_at": 1735689825,
  "started_at": 1735689830,
  "finished_at": null,
  "updated_at": 1735689860
}

Run statuses

Runs use the same status values as tasks:

Status	Description
`waiting`	Run has been created
`validating`	Inputs are being validated
`queued`	Run is queued for processing
`processing`	Tasks are being processed
`finishing`	All tasks are wrapping up
`succeeded`	All tasks completed successfully
`failed`	One or more tasks failed
`cancelled`	Run was cancelled

Sequential tasks with `next`

Use the next field to chain tasks sequentially. Tasks in next run after the parent task completes:

{
  "tasks": [
    {
      "kind": "ingest",
      "options": {
        "url": "https://example.com/video.mp4"
      },
      "next": [
        {
          "kind": "video",
          "options": {
            "width": 1280,
            "format": "mp4"
          },
          "next": [
            {
              "kind": "image",
              "options": {
                "width": 640,
                "format": "jpeg"
              }
            }
          ]
        },
        {
          "kind": "speech"
        }
      ]
    }
  ]
}

In this example:

The video is ingested first
Then a 720p version is created and speech transcription runs in parallel
After the 720p video is created, a thumbnail is extracted from it

Conditional tasks

Add conditions to control which tasks run based on the input file properties:

{
  "tasks": [
    {
      "kind": "ingest",
      "options": {
        "url": "https://example.com/video.mp4"
      },
      "next": [
        {
          "kind": "summary"
        },
        {
          "kind": "conditions",
          "options": {
            "kind": { "eq": "video" }
          },
          "next": [
            { "kind": "subtitles" },
            { "kind": "chapters" }
          ]
        }
      ]
    }
  ]
}

Here, summary runs for all files, but subtitles and chapters only run when the ingested file is a video.

Retrieving runs

Get a single run

curl "https://api.ittybit.com/runs/run_abcdefgh12345678" \
-H "Authorization: Bearer ITTYBIT_API_KEY"

Returns the run object with its tasks array.

List runs

curl "https://api.ittybit.com/runs?limit=10" \
-H "Authorization: Bearer ITTYBIT_API_KEY"

Supports cursor-based pagination with after, before, and limit parameters. Filter by status and control ordering with order (asc or desc).

Runs vs Tasks

	`POST /tasks`	`POST /runs`
Use case	Single operation on one file	Multi-step workflows
Input	`url` + `kind`	`tasks` array with `next` chains
Ingest	Automatic	Explicit (include `ingest` task)
Conditions	Not available	Use `conditions` kind
Chaining	Not available	Use `next` field

Runs

On this page