API Reference Uploads
Get all uploads Retrieve a list of all uploads with optional filtering and pagination.
Authorization Authorization
header
string
required
Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"
Query Parameters Pagination limit (max 100)
Required range: 1 <= x <= 100
Filter by status (pending, completed, error)
Available options:
waitingcompletedfailedexpired
Filter by creation date greater than or equal (UNIX epoch time)
Required range: x >= 0
Filter by creation date less than or equal (UNIX epoch time)
Required range: x >= 0
created.sort
default: "asc"
string
Sort by creation date (asc/desc)
Available options:
ascdesc
Responses 200 401 429
application/json Data contains the paginated upload items
Show data properties
created_at
string
date-time
required
Timestamp when the upload was created
Examples:
2025-01-01T12:00:00Z
expires_at
string
date-time
required
Timestamp when the upload will expire
Examples:
2025-01-01T12:00:00Z
Unique identifier of the upload
Examples:
upl_2G6MJiNz71bHQGNzGwKx5cJwPFS
Current status of the upload
Available options:
waitingcompletedfailedexpired
updated_at
string
date-time
required
Timestamp when the upload was updated
Examples:
2025-01-01T12:00:00Z
Short-lived completion capability, returned only on creation. POST after a successful PUT before expires_at. Requires no API key. Repeated valid calls are idempotent.
Error message of the upload
Show error properties
Additional error details or output
Available options:
setupffmpegsourceuploaddownloadingestjobunexpectedpermissiontimeoutcancelled
Additional metadata for the upload
Examples:
map[key1:value1 key2:value2]
SourceId is the id of the source that was created from the upload
Examples:
src_2G6MJiNz71bHQGNzGwKx5cJwPFS
Resolved Storage selected when the Upload was created. Absent for historical uploads.
Presigned PUT URL, returned only when creating an Upload session. Call completion_url after the PUT succeeds.
Examples:
https://s3.amazonaws.com/bucket/key
Limit indicates the maximum number of items in the current response
Offset indicates the offset of the first item in the current response
status
"success"
string
required
Status indicates the response status "success"
Total indicates the total number of items
OK
application/json Error response details
Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error: invalid token or subscription inactive
application/json Error response details
Show error properties
Code is the HTTP status code
Message is a human-readable error description
Examples:
Rate limit exceeded
type
"TooManyRequestsError"
string
required
Type indicates the error category
Available options:
TooManyRequestsError
status
"error"
string
required
Status indicates the response status "error"
Rate limit exceeded
# Get all uploads
> Retrieve a list of all uploads with optional filtering and pagination.
```json
{
"path": "/api/uploads",
"method": "get",
"schema": {
"description": "Retrieve a list of all uploads with optional filtering and pagination.",
"operationId": "listUploads",
"parameters": [
{
"description": "Filter by upload ID",
"in": "query",
"name": "id",
"schema": {
"type": "string"
}
},
{
"description": "Pagination offset",
"in": "query",
"name": "offset",
"schema": {
"default": 0,
"minimum": 0,
"type": "integer"
}
},
{
"description": "Pagination limit (max 100)",
"in": "query",
"name": "limit",
"schema": {
"default": 100,
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
{
"description": "Filter by source ID",
"in": "query",
"name": "source_id",
"schema": {
"type": "string"
}
},
{
"description": "Filter by status (pending, completed, error)",
"in": "query",
"name": "status",
"schema": {
"enum": [
"waiting",
"completed",
"failed",
"expired"
],
"type": "string"
}
},
{
"description": "Filter by creation date greater than or equal (UNIX epoch time)",
"in": "query",
"name": "created.gte",
"schema": {
"examples": [
"1764238404"
],
"format": "epoch",
"minimum": 0,
"type": "integer"
}
},
{
"description": "Filter by creation date less than or equal (UNIX epoch time)",
"in": "query",
"name": "created.lte",
"schema": {
"examples": [
"1764238404"
],
"format": "epoch",
"minimum": 0,
"type": "integer"
}
},
{
"description": "Sort by creation date (asc/desc)",
"in": "query",
"name": "created.sort",
"schema": {
"default": "asc",
"enum": [
"asc",
"desc"
],
"type": "string"
}
},
{
"description": "Filter by metadata",
"in": "query",
"name": "metadata",
"schema": {
"items": {
"items": {
"examples": [
"key1:value1",
"key2:value2"
],
"pattern": "^[^:]+:[^:]+$",
"type": "string"
},
"type": "array"
},
"type": "array"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UploadListResponse"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorAuthentication"
}
}
},
"description": "Authentication error: invalid token or subscription inactive"
},
"429": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ResponseErrorTooManyRequests"
}
}
},
"description": "Rate limit exceeded"
}
},
"security": [
{
"ProjectAccessToken": []
}
],
"summary": "Get all uploads",
"tags": [
"Uploads"
],
"x-codeSamples": [
{
"lang": "JavaScript",
"source": "import Chunkify from '@chunkify/chunkify';\n\nconst client = new Chunkify({\n projectAccessToken: 'My Project Access Token',\n});\n\n// Automatically fetches more pages as needed.\nfor await (const upload of client.uploads.list()) {\n console.log(upload.id);\n}"
},
{
"lang": "Python",
"source": "from chunkify import Chunkify\n\nclient = Chunkify(\n project_access_token=\"My Project Access Token\",\n)\n\n# Automatically fetches more pages as needed.\nfor upload in client.upoads.list():\n print(upload.id)"
},
{
"lang": "php",
"source": "\u003c?php\n\nuse Chunkify\\Client;\n\n$client = new Client(\n projectAccessToken: 'My Project Access Token',\n);\n\n// Automatically fetches more pages as needed.\nforeach ($client-\u003euploads-\u003elist()-\u003epagingEachItem() as $upload) {\n var_dump($upload-\u003eid);\n}"
},
{
"lang": "Go",
"source": "package main\n\nimport (\n \"context\"\n \"fmt\"\n\n \"github.com/chunkifydev/chunkify-go\"\n \"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n client := chunkify.NewClient(\n option.WithProjectAccessToken(\"My Project Access Token\"),\n )\n page, err := client.Uploads.List(context.TODO(), chunkify.UploadListParams{})\n if err != nil {\n panic(err.Error())\n }\n\n // Loop through the pages and print the upload IDs\n for page != nil {\n for _, upload := range page.Data {\n fmt.Printf(\"%+v\\n\", upload.ID)\n }\n page, err = page.GetNextPage()\n if err != nil {\n panic(err.Error())\n }\n }\n}\n"
}
]
}
}
```
```json #/components/schemas/UploadListResponse
{
"description": "Paginated response containing a list of uploads",
"properties": {
"data": {
"description": "Data contains the paginated upload items",
"items": {
"$ref": "#/components/schemas/Upload"
},
"type": "array"
},
"limit": {
"description": "Limit indicates the maximum number of items in the current response",
"type": "integer"
},
"offset": {
"description": "Offset indicates the offset of the first item in the current response",
"type": "integer"
},
"status": {
"const": "success",
"description": "Status indicates the response status \"success\"",
"type": "string"
},
"total": {
"description": "Total indicates the total number of items",
"type": "integer"
}
},
"required": [
"data",
"limit",
"offset",
"status",
"total"
],
"type": "object"
}
```
```json #/components/schemas/Upload
{
"properties": {
"completion_url": {
"description": "Short-lived completion capability, returned only on creation. POST after a successful PUT before expires_at. Requires no API key. Repeated valid calls are idempotent.",
"type": "string"
},
"created_at": {
"description": "Timestamp when the upload was created",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"error": {
"allOf": [
{
"$ref": "#/components/schemas/ChunkifyError"
}
],
"description": "Error message of the upload"
},
"expires_at": {
"description": "Timestamp when the upload will expire",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"id": {
"description": "Unique identifier of the upload",
"examples": [
"upl_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"description": "Additional metadata for the upload",
"examples": [
{
"key1": "value1",
"key2": "value2"
}
],
"type": "object"
},
"source_id": {
"description": "SourceId is the id of the source that was created from the upload",
"examples": [
"src_2G6MJiNz71bHQGNzGwKx5cJwPFS"
],
"type": "string"
},
"status": {
"description": "Current status of the upload",
"enum": [
"waiting",
"completed",
"failed",
"expired"
],
"examples": [
"waiting"
],
"type": "string"
},
"storage_id": {
"description": "Resolved Storage selected when the Upload was created. Absent for historical uploads.",
"type": "string"
},
"updated_at": {
"description": "Timestamp when the upload was updated",
"examples": [
"2025-01-01T12:00:00Z"
],
"format": "date-time",
"type": "string"
},
"upload_url": {
"description": "Presigned PUT URL, returned only when creating an Upload session. Call completion_url after the PUT succeeds.",
"examples": [
"https://s3.amazonaws.com/bucket/key"
],
"type": "string"
}
},
"required": [
"created_at",
"expires_at",
"id",
"status",
"updated_at"
],
"type": "object"
}
```
```json #/components/schemas/ChunkifyError
{
"properties": {
"detail": {
"description": "Additional error details or output",
"type": "string"
},
"message": {
"description": "Main error message",
"type": "string"
},
"type": {
"description": "Type of error",
"enum": [
"setup",
"ffmpeg",
"source",
"upload",
"download",
"ingest",
"job",
"unexpected",
"permission",
"timeout",
"cancelled"
],
"type": "string"
}
},
"required": [
"type",
"message",
"detail"
],
"type": "object"
}
```
```json #/components/schemas/ResponseErrorAuthentication
{
"description": "Error response",
"properties": {
"error": {
"description": "Error response details",
"properties": {
"code": {
"const": 401,
"description": "Code is the HTTP status code",
"examples": [
401
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Authentication error: invalid token or subscription inactive"
],
"type": "string"
},
"type": {
"const": "AuthenticationError",
"description": "Type indicates the error category",
"enum": [
"AuthenticationError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
],
"type": "object"
}
```
```json #/components/schemas/ResponseErrorTooManyRequests
{
"description": "Error response",
"properties": {
"error": {
"description": "Error response details",
"properties": {
"code": {
"const": 429,
"description": "Code is the HTTP status code",
"examples": [
429
],
"type": "integer"
},
"message": {
"description": "Message is a human-readable error description",
"examples": [
"Rate limit exceeded"
],
"type": "string"
},
"type": {
"const": "TooManyRequestsError",
"description": "Type indicates the error category",
"enum": [
"TooManyRequestsError"
],
"type": "string"
}
},
"required": [
"type",
"code",
"message"
],
"type": "object"
},
"status": {
"const": "error",
"description": "Status indicates the response status \"error\"",
"type": "string"
}
},
"required": [
"status",
"error"
],
"type": "object"
}
```