FlowData

How do I query usage, jobs and system status of media processing through the API?

Published on 10. November 2026

Besides starting jobs, media processing has a few endpoints that help your application keep track: fetch monthly figures, find jobs by your own reference, cancel a job and check whether media processing is running normally.

Querying usage for a period

GET /v1/media/usage returns your team's figures for a period. Without parameters it covers the current month up to today. With from and to in the format YYYY-MM-DD you choose your own period, and both days are included.

curl "https://api.flowdata.one/v1/media/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer fd_YOUR_KEY"
{
  "from": "2026-10-01",
  "to": "2026-10-31",
  "jobs": 148,
  "failed": 3,
  "processing_seconds": 9412.6,
  "input_bytes": 31845120384,
  "by_pipeline": {"chat_video": 92, "chat_image": 41, "course_video": 15}
}

The numbers in the example are made up.

  • jobs: number of jobs created in the period.
  • failed: how many of them failed.
  • processing_seconds: total processing time in seconds.
  • input_bytes: total size of all input files in bytes.
  • by_pipeline: number of jobs per pipeline.

These figures describe jobs, not amounts. What the jobs cost you is in FlowData under Billing, see FlowData billing, balance and spend limit.

If from is after to or the date format is wrong, you get HTTP 422 with the code validation_failed.

Finding jobs by your reference

If you give a reference when starting a job, such as an order or product number, you can find all its jobs again:

curl "https://api.flowdata.one/v1/media/jobs?reference=order:4711" \
  -H "Authorization: Bearer fd_YOUR_KEY"

The response contains up to the 20 most recent jobs with exactly this reference under data, newest first. Each entry has the same form as for GET /v1/media/jobs/{id}. Without reference, or with more than 191 characters, the API answers with HTTP 422. There's no API listing of all jobs without a reference. You'll find those in FlowData under Jobs, where you can also search for your reference.

Looking up or cancelling a job

  • GET /v1/media/jobs/{id} returns a job of your team. The API answers HTTP 404 for jobs of other teams and unknown IDs.
  • DELETE /v1/media/jobs/{id} cancels a waiting job immediately and requests cancellation of a running one. The response is the job in its new state.

What exactly happens on cancellation is covered in How do I track the status of my media jobs?.

Checking whether media processing is running

GET /v1/media/health doesn't need a key. You can add it to your monitoring, for example:

curl "https://api.flowdata.one/v1/media/health"
{"status":"ok","queue":{"pending":2,"processing":1},"version":"1.0.0"}
  • status: ok when everything is running normally. degraded means media processing is limited, for example during announced maintenance or when image processing isn't available at the moment. With down, no jobs are being processed right now.
  • queue.pending, queue.processing: waiting and running jobs across the whole platform, not just your team. A long queue explains why a job starts later.
  • version: the media processing version.

Good to know

  • Endpoints that use a key count towards the media processing rate limit of 600 requests per minute per key, like all its requests. So don't poll a job's status every second. Webhooks, which report on their own, are more convenient, see How do I set up webhooks for media processing?.
  • All media processing errors have the form {"error":{"code":"...","message":"...","details":{...},"type":"..."}}.

Was this article helpful?

Back to Media processing