List tasks

Your tasks, newest first. The filter parameters narrow the list.

GEThttps://api.switchfile.io/v2/tasks

Needs an API key: Authorization: Bearer YOUR_API_KEY. See Authentication.

Example

Request

curl "https://api.switchfile.io/v2/tasks" \
  -H "Authorization: Bearer $SWITCHFILE_API_KEY"

const res = await fetch("https://api.switchfile.io/v2/tasks", {
  headers: {
    Authorization: `Bearer ${process.env.SWITCHFILE_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
console.log(await res.json());

<?php
$ch = curl_init('https://api.switchfile.io/v2/tasks');
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SWITCHFILE_API_KEY'),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    throw new RuntimeException("HTTP $status: $response");
}
print_r(json_decode($response, true));

import os
import requests

res = requests.get(
    "https://api.switchfile.io/v2/tasks",
    headers={"Authorization": f"Bearer {os.environ['SWITCHFILE_API_KEY']}"},
)
res.raise_for_status()
print(res.json())

Parameters

Query parameters

filter[job_id]string (uuid)
Only tasks of this job
filter[status]string
Only tasks with this status
one of "waiting", "processing", "finished", "error"
filter[operation]string
Only tasks with this operation, for example convert
includestring
Extra data to include, comma-separated: retries, depends_on_tasks
pagenumber
Page number, starting at 1
at least 1
per_pagenumber
Entries per page, 100 by default
1 to 1000

Responses

200OK
dataTaskDetail[]required
data[].codestring | nullrequired
data[].copy_of_task_idstring (uuid) | nullrequired
data[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].creditsstring (integer) | integerrequired
data[].depends_on_task_idsstring (uuid)[]required
data[].depends_on_tasksmap of string (uuid)
Name and ID of each input task
keys match ^(.*)$
data[].ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].host_namestring | nullrequired
data[].idstring (uuid)required
data[].jobJob
data[].job.created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.idstring (uuid)required
data[].job.linksobjectrequired
data[].job.links.selfstringrequired
data[].job.started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.statusstringrequired
one of "waiting", "processing", "finished", "error"
data[].job.tagstring | nullrequired
data[].job.tasksTask[]
data[].job.tasks[].codestring | nullrequired
data[].job.tasks[].copy_of_task_idstring (uuid) | nullrequired
data[].job.tasks[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.tasks[].creditsstring (integer) | integerrequired
data[].job.tasks[].depends_on_task_idsstring (uuid)[]required
data[].job.tasks[].ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.tasks[].enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].job.tasks[].engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].job.tasks[].host_namestring | nullrequired
data[].job.tasks[].idstring (uuid)required
data[].job.tasks[].job_idstring (uuid)required
data[].job.tasks[].linksobjectrequired
data[].job.tasks[].messagestring | nullrequired
data[].job.tasks[].namestringrequired
data[].job.tasks[].operationstringrequired
data[].job.tasks[].percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data[].job.tasks[].prioritystring (integer) | integerrequired
data[].job.tasks[].regionstringrequired
Region the task runs in (eu-central)
data[].job.tasks[].resultTaskResultrequired
data[].job.tasks[].retry_of_task_idstring (uuid) | nullrequired
data[].job.tasks[].started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].job.tasks[].statusstringrequired
one of "waiting", "processing", "finished", "error"
data[].job.tasks[].storagestring | nullrequired
data[].job.tasks[].user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data[].job.tasks[].waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
data[].job_idstring (uuid)required
data[].linksobjectrequired
data[].links.selfstringrequired
data[].messagestring | nullrequired
data[].namestringrequired
data[].operationstringrequired
data[].payloadmap of any
keys match ^(.*)$
data[].percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data[].prioritystring (integer) | integerrequired
data[].regionstringrequired
Region the task runs in (eu-central)
data[].resultTaskResultrequired
data[].result.filesResultFile[]
data[].result.files[].detected_input_formatstring
convert only: the format the input actually had, when it differs from the given format or the file extension (for example a PNG file named .jpg)
data[].result.files[].filenamestringrequired
data[].result.files[].notesstring[]
convert only: notes when the output differs from the request, for example a frame rate the target format does not support that was set to the nearest allowed value
data[].result.files[].sizestring (integer) | integer
data[].result.files[].urlstring
data[].result.formUploadForm
data[].result.form.parametersobjectrequired
data[].result.form.urlstringrequired
data[].result.uploadDirectUpload
import/upload only: a signed URL for large files, without the 100 MB limit of result.form. The task finishes on its own a few seconds after the PUT. Call POST /v2/tasks/{id}/upload-complete to finish it right away.
data[].result.upload.expires_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].result.upload.headersmap of stringrequired
Headers the PUT request must send (usually none)
keys match ^(.*)$
data[].result.upload.max_file_sizestring (integer) | integerrequired
Largest allowed file in bytes. A larger upload makes the task fail
data[].result.upload.methodstringrequired
one of "PUT"
data[].result.upload.urlstringrequired
Signed URL. Send the file as the raw body of a PUT request, not as a form
data[].retriesTask[]
data[].retries[].codestring | nullrequired
data[].retries[].copy_of_task_idstring (uuid) | nullrequired
data[].retries[].created_atstringrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].retries[].creditsstring (integer) | integerrequired
data[].retries[].depends_on_task_idsstring (uuid)[]required
data[].retries[].ended_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].retries[].enginestring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].retries[].engine_versionstring | nullrequired
Internal identifier, may change. Do not rely on its value
data[].retries[].host_namestring | nullrequired
data[].retries[].idstring (uuid)required
data[].retries[].job_idstring (uuid)required
data[].retries[].linksobjectrequired
data[].retries[].links.selfstringrequired
data[].retries[].messagestring | nullrequired
data[].retries[].namestringrequired
data[].retries[].operationstringrequired
data[].retries[].percentstring (integer) | integerrequired
Progress as in CloudConvert: 100 when finished, otherwise 0
0 to 100
data[].retries[].prioritystring (integer) | integerrequired
data[].retries[].regionstringrequired
Region the task runs in (eu-central)
data[].retries[].resultTaskResultrequired
data[].retries[].result.filesResultFile[]
data[].retries[].result.formUploadForm
data[].retries[].result.uploadDirectUpload
import/upload only: a signed URL for large files, without the 100 MB limit of result.form. The task finishes on its own a few seconds after the PUT. Call POST /v2/tasks/{id}/upload-complete to finish it right away.
data[].retries[].retry_of_task_idstring (uuid) | nullrequired
data[].retries[].started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].retries[].statusstringrequired
one of "waiting", "processing", "finished", "error"
data[].retries[].storagestring | nullrequired
data[].retries[].user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data[].retries[].waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
data[].retry_of_task_idstring (uuid) | nullrequired
data[].started_atstring | nullrequired
ISO 8601 timestamp, for example 2026-11-06T18:00:00+00:00
data[].statusstringrequired
one of "waiting", "processing", "finished", "error"
data[].storagestring | nullrequired
data[].user_idstring | nullrequired
Account of the job (opaque ID, the same as data.id in /v2/users/me)
data[].waiting_forstring
What a waiting task waits for, one of "upload", "inputs", "queued". Only set while status is waiting
linksPageLinksrequired
links.firststringrequired
links.laststring | nullrequired
links.nextstring | nullrequired
links.prevstring | nullrequired
metaPageMetarequired
meta.current_pagestring (integer) | integerrequired
meta.current_page_urlstringrequired
meta.fromstring (integer) | integerrequired
meta.pathstringrequired
meta.per_pagestring (integer) | integerrequired
meta.tostring (integer) | integerrequired
200 application/json
```
{
  "data": [
    {
      "id": "5b7d2e90-1a3c-4f6e-8d2b-9c0a4e7f1b52",
      "job_id": "6e2c1b1f-3c1a-4d4e-9a57-0d7b2f6a8e10",
      "name": "convert-1",
      "operation": "convert",
      "status": "finished",
      "message": null,
      "code": null,
      "credits": 2,
      "created_at": "2026-11-06T18:00:00+00:00",
      "started_at": "2026-11-06T18:00:01+00:00",
      "ended_at": "2026-11-06T18:00:02+00:00",
      "depends_on_task_ids": [
        "c1f3a9d2-7e44-4b0a-a1b5-2f0e8c9d6a31"
      ],
      "retry_of_task_id": null,
      "copy_of_task_id": null,
      "priority": 0,
      "host_name": null,
      "storage": null,
      "engine": null,
      "engine_version": null,
      "percent": 100,
      "region": "eu-central",
      "user_id": "4f8a2c6e-1b3d-4e5f-8a7c-9d0b2e4f6a18",
      "result": {
        "files": [
          {
            "filename": "report.pdf",
            "size": 61544
          }
        ]
      },
      "links": {
        "self": "https://api.switchfile.io/v2/tasks/5b7d2e90-1a3c-4f6e-8d2b-9c0a4e7f1b52"
      }
    }
  ],
  "links": {
    "first": "https://api.switchfile.io/v2/tasks?page=1",
    "last": null,
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "current_page_url": "https://api.switchfile.io/v2/tasks?page=1",
    "from": 1,
    "path": "https://api.switchfile.io/v2/tasks",
    "per_page": 100,
    "to": 1
  }
}
```

401The API key is missing or not validUNAUTHENTICATED

401 application/json

{
  "message": "Missing or invalid API key.",
  "code": "UNAUTHENTICATED"
}

404Does not exist for this accountNOT_FOUND
404 application/json
```
{
  "message": "Task not found.",
  "code": "NOT_FOUND"
}
```

422Invalid data. errors names the fieldsINVALID_DATA

422 application/json

{
  "message": "id: Expected string to match 'uuid' format",
  "code": "INVALID_DATA",
  "errors": {
    "id": [
      "Expected string to match 'uuid' format"
    ]
  }
}

429Too many requests or a daily quota is used up. See Retry-AfterRATE_LIMIT_EXCEEDED
429 application/json
```
{
  "message": "Too many requests. Try again in 12 seconds.",
  "code": "RATE_LIMIT_EXCEEDED"
}
```

Error bodies and codes are explained in Errors.