Get Jobs

Retrieve a paginated list of video generation jobs for an organization

Get Jobs

Retrieve a paginated list of video generation jobs for an organization. The response is optimized for API consumption with a flat structure containing only essential fields and a shorts count.

Endpoint

GET /api/jobs

Authentication

This endpoint requires authentication. You can authenticate using either:

Bearer Token: Include your JWT token in the Authorization header
API Key: Include your API key in the X-API-Key header

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	string	No	"10"	Number of jobs to return per page (max: 100)
`offset`	string	No	"0"	Number of jobs to skip for pagination
`query`	string	No	-	Search term to filter jobs by title (case-insensitive)
`status`	string	No	-	Filter jobs by status (e.g., 'COMPLETED', 'PROCESSING', 'FAILED'). Use 'all' to show all statuses

Request Example

# Using Bearer Token
curl -X GET "https://api.example.com/api/jobs?limit=20&offset=0&status=COMPLETED" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response

The response format is optimized for API consumption with a simplified structure containing only essential fields and shorts count.

Success Response (200)

{
  "data": [
    {
      "id": "job_123",
      "title": "My Video Generation",
      "cost": 2.50,
      "costBreakDown": {
        "shortGen": 0.205,
        "youtubeProcessing": 0.72
      },
      "status": "COMPLETED",
      "source": "API",
      "progress": 100,
      "shortsCount": 5
    },
    {
      "id": "job_124",
      "title": "Another Video",
      "cost": 1.75,
      "costBreakDown": {
        "shortGen": 0.15,
        "youtubeProcessing": 0.60
      },
      "status": "PROCESSING",
      "source": "API",
      "progress": 60,
      "shortsCount": 0
    }
  ],
  "total": 2
}

Response Fields

Field	Type	Description
`data`	array	Array of job objects
`total`	number	Total number of jobs matching the filters

Job Object Fields

Field	Type	Description
`id`	string	Unique identifier for the job
`title`	string \| null	Job title or name
`cost`	number \| null	Cost of the job in credits (only present when `status` is `COMPLETED`)
`costBreakDown`	object \| null	Detailed breakdown of costs by service
`status`	string \| null	Current job status (COMPLETED, PROCESSING, FAILED, etc.)
`source`	string \| null	Source of the job (API or WEB_APP)
`progress`	number	Progress percentage (0-100) indicating the current processing stage
`shortsCount`	number	Number of generated shorts (0 if no shorts were generated or job is not completed)

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "Not allowed"
}

Notes

Response Structure

The response contains only essential fields for API consumption:

Job information: Basic job details including id, title, status, source, and progress
Cost information: cost and costBreakDown (only present when job is completed)
Shorts count: shortsCount indicates the number of generated shorts

Data Fields Usage

shortsCount: Use this field to determine if a job has generated content and how many shorts were created
status: Use this field to determine job completion state
progress: Use this field to track job processing progress (0-100)
cost: Use this field for billing and credit calculations

Pagination

The endpoint supports standard pagination:

Use limit to control page size (recommended: 10-50)
Use offset to navigate through pages
The total field helps calculate total pages: Math.ceil(total / limit)

Search and Filtering

Search: Use the query parameter to search job titles (case-insensitive)
Status Filtering: Filter by specific job statuses or use 'all' for all statuses
Combined Filters: Search and status filters can be used together

Example Use Cases

Get Recent Jobs

GET /api/jobs?limit=10&offset=0

Search for Specific Jobs

GET /api/jobs?query=youtube&limit=20

Get Completed Jobs Only

GET /api/jobs?status=COMPLETED&limit=50

Get Jobs with Pagination

# First page
GET /api/jobs?limit=20&offset=0

# Second page
GET /api/jobs?limit=20&offset=20

# Third page
GET /api/jobs?limit=20&offset=40

API Integration Examples

JavaScript/Node.js

const response = await fetch('/api/jobs?limit=20&status=COMPLETED', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const { data: jobs, total } = await response.json();

// Process jobs with shorts count
jobs.forEach(job => {
  if (job.shortsCount > 0) {
    console.log(`Job ${job.id} has ${job.shortsCount} shorts`);
  }
  
  if (job.status === 'COMPLETED' && job.cost) {
    console.log(`Job ${job.id} cost: $${job.cost}`);
  }
});

Python

import requests

response = requests.get(
    'https://api.example.com/api/jobs',
    params={'limit': 20, 'status': 'COMPLETED'},
    headers={'Authorization': f'Bearer {token}'}
)

data = response.json()
jobs = data['data']
total = data['total']

# Process jobs
for job in jobs:
    if job['shortsCount'] > 0:
        print(f"Job {job['id']} has {job['shortsCount']} shorts")
    
    if job['status'] == 'COMPLETED' and job.get('cost'):
        print(f"Job {job['id']} cost: ${job['cost']}")

cURL with Pagination

# Get first 20 jobs
curl -X GET "https://api.example.com/api/jobs?limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get next 20 jobs
curl -X GET "https://api.example.com/api/jobs?limit=20&offset=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Rate Limiting

This endpoint is subject to rate limiting. Please refer to the Rate Limiting documentation for details.

Get Job - Get details of a specific job
Create Job - Create a new video generation job

Get Jobs

On this page