# List films

`GET https://api.cream-ai.de/api/v1/films`

Films of the company, sorted by `created_at` (oldest first), then `id`; new films usually appear at the end. Lists the films of the company that were ordered through the API; every active API access of the company can read them. Projects created in mint are not listed (other sources may be added later). Each film appears at most once while paging. A film created in the same second as a page is read can, rarely, be sorted before the cursor. With `status` mint filters while reading: a page can be shorter than `limit` (even empty) and still have `has_more: true`; keep paging with `next_cursor`. `limit` is 1–100. Title and category in the list can be up to 10 minutes behind mint; `GET /films/{id}` shows the current state. A film deleted in mint disappears from the list.

Scopes: `films:read`

## Parameters

- `limit` (query): Page size (1–100).
- `cursor` (query): Opaque cursor from next_cursor of the previous page.
- `status` (query): Only films with this status.
- `video_key` (query): Only films with this video_key (all versions, exact match, case-sensitive).
- `category_id` (query): Only films in this category; for a top-level category also in its subcategories.
- `source` (query): api: films ordered through the API (default and currently the only value; other sources may be added later).

## Returns

- 200: One page of films.

## Errors

- 400: Invalid request (invalid_request, invalid_json, invalid_cursor, idempotency_key_required, invalid_idempotency_key, parent_not_found, max_depth_exceeded, narration_too_long, user_not_in_company, template_not_found, category_not_found, feedback_kind_unsupported, upload_not_found).
- 401: Missing, malformed, revoked or expired API key (unauthorized).
- 403: Not allowed (forbidden_scope, ip_not_allowed, company_inactive, api_not_enabled).
- 429: Too many requests (rate_limited).
- 500: Internal error (internal). Quote the request id when you contact support.
- 503: Temporarily unavailable (service_unavailable). Retry later (after Retry-After seconds, if sent).

## Example request

```sh
curl "https://api.cream-ai.de/api/v1/films?status=approved&limit=20" \
  -H "Authorization: Bearer $MINT_API_KEY"
```

## Example response (200)

```json
{
  "object": "list",
  "data": [
    {
      "object": "film",
      "id": "k7m2xq9v4t8n1b5r3c6d0wza",
      "title": "Lesson 3: Market segmentation",
      "status": "approved",
      "stage": "approved",
      "attention_required": false,
      "notice": null,
      "source": "api",
      "automation": "storyboard",
      "video_key": "MKT101-lesson-03",
      "version": "1.0",
      "previous_version_id": null,
      "is_latest_approved_version": true,
      "language": "de",
      "template": "lesson-standard",
      "settings": {
        "format": "16x9",
        "style_id": "b6ed57e1-2c4f-4b8a-9d3e-6f1a0c2b7e45",
        "style_revision": 4,
        "brand_id": "brand-northwind-x7k2p9",
        "voice_id": "Xb7hH8MSUJpSbSDYk0k2",
        "voice_name": "Clara",
        "narration_mode": "verbatim",
        "tempo": "presenting",
        "freedom": 40,
        "video_share": 25,
        "target_duration_s": 180
      },
      "category": {
        "object": "category",
        "id": "rz3p8w1d6c0b",
        "name": "MKT101 Marketing basics",
        "external_key": "MKT101",
        "parent": {
          "id": "mk7t2q9x4v1n",
          "name": "Marketing",
          "external_key": "MKT"
        }
      },
      "requested_by": {
        "kind": "user",
        "email": "anna.schmidt@example.edu",
        "name": "Anna Schmidt"
      },
      "metadata": {
        "course_id": "MKT101",
        "lesson": 3
      },
      "approval": {
        "revision": 2,
        "approved_at": "2026-11-11T14:30:00Z",
        "sha256": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
        "bytes": 48213377,
        "duration_s": 184.6,
        "resolution": "1920x1080",
        "mime": "video/mp4",
        "has_subtitles": true,
        "approved_by": {
          "kind": "user",
          "name": "Anna Schmidt",
          "email": "anna.schmidt@example.edu"
        }
      },
      "cancelled_at": null,
      "created_at": "2026-11-10T08:00:00Z",
      "updated_at": "2026-11-11T14:30:00Z",
      "app_url": "https://app.cream-ai.de/editorial/k7m2xq9v4t8n1b5r3c6d0wza",
      "file_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/file",
      "subtitles_url": "https://api.cream-ai.de/api/v1/films/k7m2xq9v4t8n1b5r3c6d0wza/subtitles.srt"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```