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 instead of full nested video objects.

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
`organizationId`	string	No	-	Organization ID (optional when using API key authentication)
`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"

# Using API Key
curl -X GET "https://api.example.com/api/jobs?limit=20&offset=0&status=COMPLETED" \
  -H "X-API-Key: YOUR_API_KEY"

Response

Success Response (200)

{
  "data": [
    {
      "id": "job_123",
      "title": "My Video Generation",
      "description": "Creating shorts from YouTube video",
      "cost": 2.50,
      "creditUsageStatus": "ACTIVE",
      "status": "COMPLETED",
      "functionName": "VideoShorts",
      "source": "WEB_APP",
      "createdAt": "2024-01-15T10:30:00Z",
      "shortsCount": 5
    },
    {
      "id": "job_124",
      "title": "Another Video",
      "description": null,
      "cost": 1.75,
      "creditUsageStatus": "ACTIVE",
      "status": "COMPLETED",
      "functionName": "VideoShorts",
      "source": "API",
      "createdAt": "2024-01-15T09:15:00Z",
      "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	Job title or name
`description`	string \| null	Optional job description
`cost`	number	Cost of the job in credits
`creditUsageStatus`	string	Status of credit usage (ACTIVE, PENDING, etc.) - affects cost styling
`status`	string \| null	Current job status (COMPLETED, PROCESSING, FAILED, etc.)
`functionName`	string	Type of job function (VideoShorts, StoryGenerator, etc.)
`source`	string	Source of the job (API or WEB_APP)
`createdAt`	string	ISO 8601 timestamp when the job was created
`shortsCount`	number	Number of generated shorts (0 if no shorts were generated)

Error Responses

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "Not allowed"
}

Notes

Data Optimization

This endpoint is optimized for API performance:

No nested video objects: Instead of returning full video data, only shortsCount is provided
Eliminated unnecessary fields: Files, organization details, and other sensitive information are excluded
Efficient database queries: Only essential fields are fetched from the database
Reduced payload size: Smaller response sizes for faster API calls and reduced bandwidth usage

Response Structure

The response is designed for efficient API consumption:

Flat structure: No nested objects for better parsing and processing
Essential fields only: Contains only the data needed for job management
Shorts count: Direct shortsCount field instead of nested video objects
Credit status: creditUsageStatus field for business logic decisions

Data Fields Usage

shortsCount: Use this field to determine if a job has generated content
creditUsageStatus: Use this field to determine credit validity and billing status
status: Use this field to determine job completion state
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.creditUsageStatus === 'ACTIVE') {
    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['creditUsageStatus'] == 'ACTIVE':
        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