List Requests

`GET /shorts`

Returns a paginated list of all your API-created short requests. Use this endpoint to monitor the status of multiple requests at once, browse your history, or find completed requests.

Query parameters

Parameter	Type	Default	Description
`page`	number	`1`	Page number (starting from 1)
`limit`	number	`20`	Items per page (1–100)
`status`	string	—	Filter by status: `queued`, `processing`, `completed`, `failed`, or `cancelled`
`sortBy`	string	`createdAt`	Sort field: `createdAt` or `updatedAt`
`sortOrder`	string	`desc`	Sort direction: `asc` (oldest first) or `desc` (newest first)

Request

curl -H "X-API-Key: sk_ssemble_your_key" \
  "https://aiclipping.ssemble.com/api/v1/shorts?page=1&limit=10&status=completed"

Response

{
  "data": {
    "requests": [
      {
        "requestId": "665a1b2c3d4e5f6a7b8c9d0e",
        "status": "completed",
        "progress": 100,
        "createdAt": "2024-06-01T12:00:00.000Z",
        "updatedAt": "2024-06-01T12:25:00.000Z",
        "url": "https://www.youtube.com/watch?v=...",
        "duration": 600
      },
      {
        "requestId": "665a1b2c3d4e5f6a7b8c9d0f",
        "status": "processing",
        "progress": 45,
        "createdAt": "2024-06-01T12:30:00.000Z",
        "updatedAt": "2024-06-01T12:35:00.000Z",
        "url": "https://www.youtube.com/watch?v=...",
        "duration": 300
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "totalPages": 5,
      "totalCount": 42
    }
  }
}

Response fields

Request object

Field	Type	Description
`requestId`	string	Unique request identifier — use with `GET /shorts/:id` to get full details
`status`	string	Current processing status: `queued`, `processing`, `completed`, `failed`, or `cancelled`
`progress`	number	Processing progress percentage (0–100)
`createdAt`	string	ISO 8601 timestamp when the request was created
`updatedAt`	string	ISO 8601 timestamp of the last status update
`url`	string	Original video URL that was submitted
`duration`	number	Requested time range in seconds (`end - start`)

Pagination object

Field	Type	Description
`page`	number	Current page number
`limit`	number	Items per page
`totalPages`	number	Total number of pages available
`totalCount`	number	Total number of matching requests

Filtering by status

Use the status parameter to filter requests by their processing state:

# Only show completed requests
curl -H "X-API-Key: sk_ssemble_your_key" \
  "https://aiclipping.ssemble.com/api/v1/shorts?status=completed"
 
# Only show requests still processing
curl -H "X-API-Key: sk_ssemble_your_key" \
  "https://aiclipping.ssemble.com/api/v1/shorts?status=processing"
 
# Only show failed requests for investigation
curl -H "X-API-Key: sk_ssemble_your_key" \
  "https://aiclipping.ssemble.com/api/v1/shorts?status=failed"

If no status parameter is provided, all requests are returned regardless of status.

Sorting

Control the order of results with sortBy and sortOrder:

# Most recently created first (default)
?sortBy=createdAt&sortOrder=desc
 
# Oldest first
?sortBy=createdAt&sortOrder=asc
 
# Most recently updated first (useful for finding newly completed requests)
?sortBy=updatedAt&sortOrder=desc

Pagination

Navigate through large result sets using page and limit:

async function getAllCompletedRequests(apiKey) {
  const allRequests = [];
  let page = 1;
  let totalPages = 1;
 
  while (page <= totalPages) {
    const response = await fetch(
      `https://aiclipping.ssemble.com/api/v1/shorts?status=completed&page=${page}&limit=100`,
      { headers: { 'X-API-Key': apiKey } }
    );
    const { data } = await response.json();
 
    allRequests.push(...data.requests);
    totalPages = data.pagination.totalPages;
    page++;
  }
 
  console.log(`Found ${allRequests.length} completed requests`);
  return allRequests;
}

Batch status monitoring

Instead of polling each request individually with GET /shorts/:id/status, use this endpoint to check the status of all active requests in a single call:

async function getActiveRequests(apiKey) {
  const response = await fetch(
    'https://aiclipping.ssemble.com/api/v1/shorts?status=processing&limit=100',
    { headers: { 'X-API-Key': apiKey } }
  );
  const { data } = await response.json();
 
  for (const req of data.requests) {
    console.log(`${req.requestId}: ${req.status} (${req.progress}%)`);
  }
 
  return data.requests;
}

This is more efficient than individual status polls and uses less of your rate limit budget.

Error responses

Status	Code	When
400	`invalid_request`	Invalid query parameter values (e.g., `page=0`, `limit=200`, invalid `status` value)
401	`invalid_api_key`	Missing or invalid API key
429	`rate_limit_exceeded`	Too many requests

Notes

Only requests created via the API with your API key are returned. Requests created through the web UI are not included.
The maximum limit is 100. Values above 100 are rejected.
The minimum page is 1. Page 0 is not valid.

On this page