Skip to content
EN
Get API key
Browse documentation

API reference

Bulk processing API

Create and control file-based YouTube jobs, then retrieve their manifests and result parts.

On this page

API playground

Choose a source and copy a complete Python or Bash workflow, a single request, or a sample response. The playground previews code; it does not submit a job. Complete workflows handle upload, status checks and retrieval of every result part.

Source parameters

Build a Bulk workflow

Local UTF-8 file, one YouTube ID per line, up to 2 GiB. Input requirements.

Advanced media options

Media destination

Blank uses the UTC media upload date (YYYYMMDD).

Add your storage credentials on your server before running the code. They need permission to upload files.

Provider credentials and storage requirements
Bulk completion webhookManifest-completion notification and verification
POSThttps://api.flashdata.dev/v2/bulk-jobs
Python 3 · standard library
import gzip
import json
import os
from pathlib import Path
import random
import re
import shutil
import time
import urllib.error
import urllib.parse
import urllib.request

api_key = "YOUR_API_KEY"
api_url = "https://api.flashdata.dev/v2"
input_file = Path("video-ids.txt")
output_dir = Path("bulk-results")
bulk_id = ""  # Paste a saved Bulk ID to monitor/retrieve it without submitting again.
poll_timeout_seconds = 1800
payload = {
    "source": "youtube_download",
    "options": {
        "download_type": "audio_video",
        "video_quality": "<=720",
        "audio_language": "default",
        "upload_metadata": False,
        "output_format": "mp4",
        "storage": {
            "storage_type": "s3",
            "storage_url": "your-media-bucket",
            "access_key": "YOUR_ACCESS_KEY",
            "secret_key": "YOUR_SECRET_KEY",
            "region": "us-east-1",
        },
    },
}

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

opener = urllib.request.build_opener(NoRedirect())
os.umask(0o077)

def api(path, method="GET", body=None):
    data = None if body is None else json.dumps(body).encode("utf-8")
    headers = {"X-API-Key": api_key, "Content-Type": "application/json"}
    for attempt in range(5):
        try:
            request = urllib.request.Request(api_url + path, data=data, headers=headers, method=method)
            with opener.open(request, timeout=60) as response:
                return json.load(response)
        except urllib.error.HTTPError as error:
            if method != "GET" or error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            retry_after = error.headers.get("Retry-After", "")
            delay = min(120, int(retry_after)) if retry_after.isdigit() else 2 ** attempt
            time.sleep(delay + random.random())

def result_location(path):
    request = urllib.request.Request(api_url + path, headers={"X-API-Key": api_key})
    try:
        with opener.open(request, timeout=60):
            raise RuntimeError("Expected a 302 result redirect")
    except urllib.error.HTTPError as error:
        if error.code != 302:
            raise
        location = error.headers.get("Location", "")
    parsed = urllib.parse.urlsplit(location)
    if parsed.scheme != urllib.parse.urlsplit(api_url).scheme or not parsed.hostname or parsed.username or parsed.password:
        raise RuntimeError("Invalid signed storage URL")
    return location

if not bulk_id:
    if not input_file.is_file() or not 1 <= input_file.stat().st_size <= 2147483648:
        raise ValueError("Use a nonempty UTF-8 ID file up to 2 GiB")
    created = api("/bulk-jobs", "POST", payload)
    bulk_id = created["job"]["id"]
    if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
        raise RuntimeError("Invalid Bulk ID")
    work = output_dir / bulk_id
    work.mkdir(parents=True, exist_ok=True)
    (work / "created.json").write_text(json.dumps(created, indent=2))
    print("Saved Bulk ID:", bulk_id, flush=True)
    upload = created["upload"]
    upload_url = urllib.parse.urlsplit(upload["href"])
    if upload["method"] != "PUT" or upload_url.scheme != urllib.parse.urlsplit(api_url).scheme or not upload_url.hostname or upload_url.username or upload_url.password:
        raise RuntimeError("Invalid signed upload URL")
    with input_file.open("rb") as file:
        request = urllib.request.Request(upload["href"], data=file, method="PUT", headers={
            "Content-Type": upload["contentType"], "Content-Length": str(input_file.stat().st_size)
        })
        with opener.open(request, timeout=120) as response:
            response.read()
    api("/bulk-jobs/" + bulk_id + "/start", "POST")

if not re.fullmatch(r"bulk_[A-Za-z0-9_-]{8,}", bulk_id):
    raise ValueError("Invalid Bulk ID")
work = output_dir / bulk_id
work.mkdir(parents=True, exist_ok=True)
deadline = time.monotonic() + poll_timeout_seconds
while True:
    job = api("/bulk-jobs/" + bulk_id)["job"]
    (work / "status.json").write_text(json.dumps(job, indent=2))
    print(job["status"], job["input"], job["counts"], flush=True)
    if job["status"] == "completed":
        break
    if job["status"] in ("paused", "failed", "cancelled", "awaiting_upload"):
        raise RuntimeError(json.dumps({"id": bulk_id, "status": job["status"], "pauseReason": job.get("pauseReason"), "error": job.get("error")}))
    if time.monotonic() >= deadline:
        raise TimeoutError("Job still running. Set bulk_id to " + bulk_id + " and rerun to continue monitoring.")
    time.sleep(10 + random.random())

manifest_url = result_location("/bulk-jobs/" + bulk_id + "/results")
with opener.open(manifest_url, timeout=60) as response:  # No API key sent to storage.
    manifest = json.load(response)
(work / "manifest.json").write_text(json.dumps(manifest, indent=2))
for part in manifest["parts"]:
    number = part["number"]
    if type(number) is not int or number < 1:
        raise RuntimeError("Invalid part number")
    path = "/bulk-jobs/" + bulk_id + "/results/" + str(number)
    if part["href"] != api_url + path:
        raise RuntimeError("Unexpected part API URL")
    storage_url = result_location(path)
    compressed = work / ("part-" + str(number) + ".jsonl.gz")
    with opener.open(storage_url, timeout=120) as response, compressed.open("wb") as file:
        shutil.copyfileobj(response, file, 1024 * 1024)
    with compressed.open("rb") as file:
        gzipped = file.read(2) == b"\x1f\x8b"
    reader = gzip.open(compressed, "rb") if gzipped else compressed.open("rb")
    with reader, (work / ("part-" + str(number) + ".jsonl")).open("wb") as file:
        shutil.copyfileobj(reader, file, 1024 * 1024)
print("Saved manifest and decoded NDJSON parts in", work)
Create, upload, start, monitor and retrieve all partsX-API-Key authentication

Endpoints

All endpoints use https://api.flashdata.dev/v2. Create a job → upload a video-ID file → start → monitor → retrieve the manifest and every result part.

MethodPathAction
POST/v2/bulk-jobsCreate a Bulk job
POST/v2/bulk-jobs/{bulkId}/startUpload and start
GET/v2/bulk-jobs/{bulkId}Get job status
GET/v2/bulk-jobsList jobs
POST/v2/bulk-jobs/{bulkId}/pausePause a job
PATCH/v2/bulk-jobs/{bulkId}Update job options
POST/v2/bulk-jobs/{bulkId}/resumeResume a job
DELETE/v2/bulk-jobs/{bulkId}Cancel a job
GET/v2/bulk-jobs/{bulkId}/resultsGet the result manifest
GET/v2/bulk-jobs/{bulkId}/results/{partNumber}Download result parts

Authentication and input

Set FLASHDATA_API_KEY to a key with access to the chosen source. Reuse the same key and account for creation, controls and results. Processing uses the account's balance and normal per-source pricing. YouTube Download requires owner access and options.storage.

Create a working folder named bulk-api/ and run these examples from it. The playground’s complete Python workflow uses the Python 3.10+ standard library; the individual Python endpoint examples below require Requests; cURL examples use Bash, cURL 7.76+, jq and gzip. Choose one language for each action so you do not create or start duplicate work.

Input is a UTF-8 file with one 11-character YouTube ID per line, up to 2 GiB. Use IDs, not URLs. Remove duplicate IDs before uploading; repeated IDs are processed separately.

SourceShared options
youtube_metadatainclude_formats, include_chapters
youtube_transcriptlanguage, auto
youtube_captionslanguage, auto
youtube_trainabilityNo options
youtube_downloadMedia options and storage destination
Python dependency
python -m pip install requests

Create request fields

FieldTypeUsage
sourcestringRequired. One supported source for every input ID.
optionsobjectShared source options. Data sources may set result_storage; YouTube Download requires storage.
callback_urlstringOptional public HTTPS completion callback. Sent after manifest publication.

Create a Bulk job

Create a job, upload a UTF-8 text file with one 11-character YouTube video ID per line to upload.href, then call start. Creating the job alone does not begin processing.

This example writes video-ids.txt and saves the 201 receipt to bulk-created.json. Keep that receipt private and reuse job.id for every later request. Creating a job leaves it in awaiting_upload; the upload URL expires after 15 minutes.

Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Save bulk_create.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

bulk_create.py
import json
import os
from pathlib import Path

import requests

os.umask(0o077)
Path("video-ids.txt").write_bytes(b"jNQXAC9IVRw\ndQw4w9WgXcQ\n")
response = requests.post(
    "https://api.flashdata.dev/v2/bulk-jobs",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"source": "youtube_metadata", "options": {"include_formats": False}},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
receipt = response.json()
Path("bulk-created.json").write_text(json.dumps(receipt, indent=2), encoding="utf-8")
print(json.dumps(receipt["job"], indent=2))
Run from bulk-api/
python bulk_create.py

Responses and request schema

HTTP statusMeaning
201Bulk job created with a 15-minute direct upload URL
401Authentication required or invalid
422Request validation failed
503A required dependency or catalog is temporarily unavailable
Request body
{
  "$ref": "#/components/schemas/CreateBulkJobRequest"
}
201 · application/json
{
  "$ref": "#/components/schemas/BulkJobCreated"
}

Upload and start

Start processing the uploaded UTF-8 video ID file, up to 2 GiB (2147483648 bytes). Keep the file unchanged after starting.

First PUT video-ids.txt to the receipt's upload.href with upload.contentType, without X-API-Key. The example calls start only after upload succeeds. Keep the uploaded file unchanged afterward.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/start
X-API-Key: YOUR_API_KEY

Save bulk_start.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

bulk_start.py
import json
import os
from pathlib import Path

import requests

receipt = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))
upload = receipt["upload"]
if upload["method"] != "PUT" or not upload["href"].startswith("https://"):
    raise ValueError("Expected an HTTPS PUT upload URL")
# Stream the file to storage without the FlashData key.
with open("video-ids.txt", "rb") as file:
    response = requests.put(
        upload["href"], data=file,
        headers={"Content-Type": upload["contentType"]},
        timeout=300, allow_redirects=False,
    )
    response.raise_for_status()
    if not 200 <= response.status_code < 300:
        raise RuntimeError("Upload did not complete; do not start the job yet")

bulk_id = receipt["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/start",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json()["job"], indent=2))
Run from bulk-api/
python bulk_start.py

Responses

HTTP statusMeaning
200Bulk job started or its current idempotent state
401Authentication required or invalid
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
503A required dependency or catalog is temporarily unavailable
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Get job status

Read job.status, input, counts, pauseReason and error. Recheck the same ID with a delay; completed means the manifest is published, not that every video succeeded.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Save bulk_status.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

bulk_status.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
Path("bulk-job.json").write_text(json.dumps(response.json(), indent=2), encoding="utf-8")
print(json.dumps(response.json()["job"], indent=2))
Run from bulk-api/
python bulk_status.py

Responses

HTTP statusMeaning
200Bulk job state
401Authentication required or invalid
404Resource not found or not owned by the caller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

List jobs

The response contains data and pagination. Pass pagination.nextCursor as the next request's cursor query parameter until it is null. Use limit from 1 to 50; the default is 20.

ParameterLocationRequirement
cursorqueryOptional · {"type":"string","maxLength":512}
limitqueryOptional · {"type":"integer","minimum":1,"maximum":50,"default":20}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs
X-API-Key: YOUR_API_KEY

Save list_bulk_jobs.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

list_bulk_jobs.py
import json
import os
from pathlib import Path

import requests

response = requests.get(
    "https://api.flashdata.dev/v2/bulk-jobs?limit=20",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Run from bulk-api/
python list_bulk_jobs.py

Responses

HTTP statusMeaning
200Bulk job page
401Authentication required or invalid
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobPage"
}

Pause a job

Pause new submissions and result packaging. Existing jobs continue with their original settings and charges. Resume the job when ready.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/pause
X-API-Key: YOUR_API_KEY

Save pause_bulk_job.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

pause_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/pause",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Run from bulk-api/
python pause_bulk_job.py

Responses

HTTP statusMeaning
200Paused bulk job or its current idempotent state
401Authentication required or invalid
404Resource not found or not owned by the caller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Update job options

Update options while awaiting upload, or while paused before all input has been read. Existing jobs keep their settings. If pausing is still in progress, wait and retry a 409 response. After all input has been read, only delivery credentials can be updated. Set callback_url to null to remove it.

This example removes the completion callback. To change source options, send an options object instead. Pause first and wait for the pause to take effect; a 409 means the update cannot be applied yet. Existing child jobs keep their original options.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
PATCH https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Save update_bulk_job.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

update_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.patch(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    json={"callback_url": None},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Run from bulk-api/
python update_bulk_job.py

Responses and request schema

HTTP statusMeaning
200Updated bulk job state
401Authentication required or invalid
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
422Request validation failed
Request body
{
  "$ref": "#/components/schemas/UpdateBulkJobRequest"
}
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Resume a job

Fix pauseReason first, such as adding credits or updating storage credentials, then resume the same Bulk ID.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
POST https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/resume
X-API-Key: YOUR_API_KEY

Save resume_bulk_job.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

resume_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.post(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/resume",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Run from bulk-api/
python resume_bulk_job.py

Responses

HTTP statusMeaning
200Current bulk job state
401Authentication required or invalid
404Resource not found or not owned by the caller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Cancel a job

Stop new submissions. Existing jobs can still finish and incur their normal charges. A cancelled job does not publish a final manifest.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
DELETE https://api.flashdata.dev/v2/bulk-jobs/{bulkId}
X-API-Key: YOUR_API_KEY

Save cancel_bulk_job.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

cancel_bulk_job.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.delete(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
print(json.dumps(response.json(), indent=2))
Run from bulk-api/
python cancel_bulk_job.py

Responses

HTTP statusMeaning
200Current bulk job state
401Authentication required or invalid
404Resource not found or not owned by the caller
200 · application/json
{
  "$ref": "#/components/schemas/BulkJobResponse"
}

Get the result manifest

Follow the redirect to download the JSON manifest and use its links to retrieve result files. Fetch signed storage URLs without your API key. Results remain available for 24 hours after the entire Bulk job completes.

The authenticated API request returns 302 with a Location header. Fetch that HTTPS storage URL in a separate request without X-API-Key. The example saves manifest.json. A 409 means results are not ready; 410 means they expired.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results
X-API-Key: YOUR_API_KEY

Save bulk_manifest.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

bulk_manifest.py
import json
import os
from pathlib import Path

import requests

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
response = requests.get(
    f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results",
    headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
    timeout=30, allow_redirects=False,
)
response.raise_for_status()
if response.status_code != 302:
    raise RuntimeError(f"Expected a manifest redirect, got {response.status_code}")
url = response.headers["Location"]
if not url.startswith("https://"):
    raise ValueError("Expected an HTTPS storage URL")

manifest = requests.get(url, timeout=120)  # No FlashData API key.
manifest.raise_for_status()
Path("manifest.json").write_text(json.dumps(manifest.json(), indent=2), encoding="utf-8")
print(json.dumps(manifest.json(), indent=2))
Run from bulk-api/
python bulk_manifest.py

Responses

HTTP statusMeaning
200JSON manifest downloaded after following the redirect
302Redirect to a short-lived private R2 URL; API credentials must not be forwarded · Location
401Authentication required or invalid
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
410The retained result has expired
200 · application/json
{
  "type": "object",
  "additionalProperties": true
}

Download result parts

Use each parts[].number from manifest.json. Each endpoint returns a 302 to a gzip NDJSON file; download without the API key, decompress, then parse one JSON object per line. Join by the zero-based index. The example retrieves all parts and keeps both .ndjson.gz and .ndjson files.

ParameterLocationRequirement
bulkIdpathRequired · {"type":"string","pattern":"^bulk_[A-Za-z0-9_-]{8,}$"}
partNumberpathRequired · {"type":"integer","minimum":0}
Endpoint
GET https://api.flashdata.dev/v2/bulk-jobs/{bulkId}/results/{partNumber}
X-API-Key: YOUR_API_KEY

Save bulk_parts.py in bulk-api/ beside bulk-created.json. Copy the complete script, then run the command below it.

bulk_parts.py
import json
import os
from pathlib import Path

import requests
import gzip
import shutil

bulk_id = json.loads(Path("bulk-created.json").read_text(encoding="utf-8"))["job"]["id"]
manifest = json.loads(Path("manifest.json").read_text(encoding="utf-8"))
for part in manifest["parts"]:
    number = part["number"]
    response = requests.get(
        f"https://api.flashdata.dev/v2/bulk-jobs/{bulk_id}/results/{number}",
        headers={"X-API-Key": os.environ["FLASHDATA_API_KEY"]},
        timeout=30, allow_redirects=False,
    )
    response.raise_for_status()
    if response.status_code != 302:
        raise RuntimeError(f"Expected a part redirect, got {response.status_code}")
    url = response.headers["Location"]
    if not url.startswith("https://"):
        raise ValueError("Expected an HTTPS storage URL")

    # Save the original gzip bytes; do not decompress twice.
    with requests.get(url, stream=True, timeout=120) as download:
        download.raise_for_status()
        with open(f"part-{number}.ndjson.gz", "wb") as file:
            download.raw.decode_content = False
            shutil.copyfileobj(download.raw, file)
    with gzip.open(f"part-{number}.ndjson.gz", "rt", encoding="utf-8") as rows:
        with open(f"part-{number}.ndjson", "w", encoding="utf-8") as file:
            for line in rows:
                file.write(line)
                print(json.dumps(json.loads(line)))
Run from bulk-api/
python bulk_parts.py

Responses

HTTP statusMeaning
200Gzip-compressed NDJSON downloaded after following the redirect
302Redirect to a short-lived private R2 URL; API credentials must not be forwarded · Location
401Authentication required or invalid
404Resource not found or not owned by the caller
409Resource state or idempotency conflict
410The retained result has expired
200 · application/x-ndjson
{
  "type": "string"
}

Job states and retention

Results remain available for 24 hours after the entire Bulk job completes. Save them before expiresAt. Media in your destination follows your bucket's retention policy. A completed job can include failed videos; counts.invalid records rejected input lines.

StateNext action
awaiting_uploadUpload the file and call start.
runningPoll the same ID with backoff; input.complete shows whether scanning finished.
pausedRead pauseReason, fix it, then resume.
finalizingWait for result packaging and manifest publication.
completedDownload the manifest and every part. Inspect each row's status and error.
failed / cancelledInspect error and saved state. No final manifest is published.

Storage delivery

Use the playground to configure a provider and preview the exact request fields. Customer storage credentials belong in the chosen storage object; X-API-Key authenticates only FlashData API requests.

SourceCreate request fieldDelivery
Metadata, transcript, captions, license checkoptions.result_storageOptional. Copies NDJSON result parts and a manifest to your bucket.
youtube_downloadoptions.storageRequired. Delivers media to your bucket; result_storage and browser_delivery are not accepted.

Find the delivered files

The data manifest is written last and lists object keys, sizes and SHA-256 checksums. It differs from the FlashData manifest, which lists API href values. YYYYMMDD in data paths uses the UTC Bulk creation date; in media paths it uses each video's UTC upload date. Bulk OSS data delivery requires an aliyuncs.com endpoint.

Private media file_url values need your storage SDK or a signed URL from that provider. A FlashData key does not grant bucket access. Optional metadata companion files are stored beside the media. Delivery retries appear in delivery.retryCount.

Data object layout
<prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz
<prefix>/<source>/<bulkId>/manifest.json

Receive a completion webhook

Place a public HTTPS callback_url outside options. Bulk sends completed only after publishing the manifest; it sends no per-video events and no completion event for failed or cancelled jobs. Keep status polling as a fallback.

  1. Persist and deduplicate delivery_id, then return 2xx promptly. Delivery retries up to eight times with backoff.
  2. Events are unsigned. Match id and source to your saved receipt; verify completed through the authenticated management API before queuing retrieval. Ignore URLs from an unverified event.
Create request with a callback
{
  "source": "youtube_metadata",
  "options": {
    "include_formats": false,
    "include_chapters": false
  },
  "callback_url": "https://your-app.example/webhooks/flashdata"
}
Completion event · illustrative
{
  "delivery_id": "bulk-completion:bulk_EXAMPLE123",
  "id": "bulk_EXAMPLE123",
  "source": "youtube_metadata",
  "status": "completed",
  "links": [
    {
      "rel": "self",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123",
      "method": "GET"
    },
    {
      "rel": "results",
      "href": "https://api.flashdata.dev/v2/bulk-jobs/bulk_EXAMPLE123/results",
      "method": "GET"
    }
  ]
}

Schema definitions

BulkJobCreated

BulkJobCreated
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job",
    "upload"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    },
    "upload": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "href",
        "method",
        "expiresAt",
        "contentType"
      ],
      "properties": {
        "href": {
          "type": "string",
          "format": "uri"
        },
        "method": {
          "type": "string",
          "const": "PUT"
        },
        "expiresAt": {
          "type": "string",
          "format": "date-time"
        },
        "contentType": {
          "type": "string",
          "const": "text/plain; charset=utf-8"
        }
      }
    }
  }
}

BulkJob

BulkJob
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "source",
    "status",
    "input",
    "counts",
    "delivery",
    "pauseReason",
    "error",
    "createdAt",
    "startedAt",
    "completedAt",
    "expiresAt",
    "links"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^bulk_[A-Za-z0-9_-]{8,}$"
    },
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "awaiting_upload",
        "running",
        "paused",
        "finalizing",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "input": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "bytes",
        "complete",
        "scannedBytes",
        "scannedLines"
      ],
      "properties": {
        "bytes": {
          "type": "integer",
          "minimum": 0
        },
        "complete": {
          "type": "boolean"
        },
        "scannedBytes": {
          "type": "integer",
          "minimum": 0
        },
        "scannedLines": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "counts": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "accepted",
        "completed",
        "failed",
        "invalid",
        "results"
      ],
      "properties": {
        "accepted": {
          "type": "integer",
          "minimum": 0
        },
        "completed": {
          "type": "integer",
          "minimum": 0
        },
        "failed": {
          "type": "integer",
          "minimum": 0
        },
        "invalid": {
          "type": "integer",
          "minimum": 0
        },
        "results": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "pauseReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "delivery": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "customerStorage",
        "storageType",
        "uploadedParts",
        "retryCount"
      ],
      "properties": {
        "customerStorage": {
          "type": "boolean"
        },
        "storageType": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "s3",
            "s3_compatible",
            "oss",
            "gcs",
            "azure",
            "cos",
            "bos",
            "tos",
            null
          ]
        },
        "uploadedParts": {
          "type": "integer",
          "minimum": 0
        },
        "retryCount": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "error": {
      "oneOf": [
        {
          "type": "null"
        },
        {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "code",
            "detail"
          ],
          "properties": {
            "code": {
              "type": "string"
            },
            "detail": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      ]
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "startedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "completedAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "expiresAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "links": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/JobLink"
      }
    }
  }
}

BulkJobPage

BulkJobPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "data",
    "pagination"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BulkJob"
      }
    },
    "pagination": {
      "$ref": "#/components/schemas/Pagination"
    }
  }
}

BulkJobResponse

BulkJobResponse
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "job"
  ],
  "properties": {
    "job": {
      "$ref": "#/components/schemas/BulkJob"
    }
  }
}

CreateBulkJobRequest

CreateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "source"
  ],
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "youtube_metadata",
        "youtube_transcript",
        "youtube_captions",
        "youtube_trainability",
        "youtube_download"
      ]
    },
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Reused for every ID. Metadata accepts include_formats and include_chapters. Transcript and captions accept language (one code or an array of 1–10 distinct codes) and auto (applies to all requested languages). Omit language to prefer en-orig, fall back to en, and return one track. With auto=true, each requested code tries its -orig track first, then the plain code. Explicit -orig codes and auto=false stay exact. languageCode identifies the selected track; requestedLanguageCode is included when it differs from the requested code. A language array returns tracks and per-language errors for each video with at least one retrieved track. If no track is retrieved, the video job fails and its reserved credits are refunded. Bulk exports use one JSONL record per video. Trainability accepts no source options. These four data sources optionally accept result_storage. Supported storage_type values are s3, s3_compatible, oss, gcs, azure, cos, bos, and tos. storage_url is the bucket name (Azure container name); object_prefix is optional. S3, S3-compatible, OSS, COS, BOS, and TOS use access_key and secret_key. S3-compatible and OSS also require a public HTTPS endpoint_url. COS, BOS, and TOS require region and use fixed provider endpoints. COS bucket names include the APPID. BOS S3-compatible HTTPS delivery supports bj, su, and hkg. GCS requires service_account with project_id, client_email, and private_key. Azure requires account_name and a container SAS sas_token with write permission. Default object_prefix is YYYYMMDD, frozen to the UTC bulk creation date. Files are written to <prefix>/<source>/<bulkId>/results/part-NNNNNNNN.jsonl.gz; manifest.json in the same bulk directory is written last. Each JSONL row includes its input index and completed, failed, or invalid status. Internal R2 results remain available through the result links for 24 hours. Download accepts the normal YouTube download parameters, requires customer storage, and does not permit browser_delivery. Download storage supports the same eight provider types and credential shapes listed above under the storage field. Download storage may include object_prefix; YYYYMMDD tokens resolve to the UTC upload date, while literal prefixes are unchanged."
    },
    "callback_url": {
      "type": "string",
      "format": "uri",
      "maxLength": 2048,
      "description": "Optional public HTTPS endpoint notified once after manifest publication."
    }
  }
}

JobLink

JobLink
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "rel",
    "href",
    "method"
  ],
  "properties": {
    "rel": {
      "type": "string",
      "enum": [
        "self",
        "results",
        "content",
        "download"
      ]
    },
    "href": {
      "type": "string",
      "format": "uri"
    },
    "method": {
      "type": "string",
      "const": "GET"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "filename": {
      "type": "string"
    },
    "content_type": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 1
    }
  }
}

Pagination

Pagination
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "hasMore",
    "limit"
  ],
  "properties": {
    "nextCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "previousCursor": {
      "type": [
        "string",
        "null"
      ]
    },
    "hasMore": {
      "type": "boolean"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  }
}

Problem

Problem
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "type",
    "title",
    "status",
    "code",
    "requestId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "format": "uri-reference"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer",
      "minimum": 400,
      "maximum": 599
    },
    "code": {
      "type": "string",
      "pattern": "^[a-z0-9_]+$"
    },
    "detail": {
      "type": "string"
    },
    "requestId": {
      "type": "string",
      "pattern": "^req_"
    },
    "fieldErrors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/FieldError"
      }
    }
  }
}

FieldError

FieldError
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "field",
    "code",
    "message"
  ],
  "properties": {
    "field": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

UpdateBulkJobRequest

UpdateBulkJobRequest
{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "options": {
      "type": "object",
      "additionalProperties": true,
      "description": "Partial option update. Nested storage fields are merged so unchanged credentials do not need to be resent. Data result_storage fields are merged the same way. After all IDs have been scanned, a paused data bulk job accepts credential updates only: access_key and secret_key, GCS service_account, or Azure sas_token, depending on the storage type. The complete merged configuration is validated before it is stored."
    },
    "callback_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "maxLength": 2048,
      "description": "Replacement completion callback, or null to remove the callback."
    }
  }
}