---
title: "Poll a generate/clip job — returns status and, when done, the produced clips"
method: GET
path: "/api/v1/jobs/{id}"
---

# Poll a generate/clip job — returns status and, when done, the produced clips

`GET /api/v1/jobs/{id}`

## Request

- Base URL: `https://everpop.app`
- URL: `https://everpop.app/api/v1/jobs/{id}`
- Auth: HTTP bearer

## Path parameters

- `id` string, required

## Response `200`

The job. Poll every 15–30s until status is not PENDING or PROCESSING.

- JobStatusEnvelope
  - `ok` unknown, required
  - `data` object, required
    - `jobId` string, required
    - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELED', required: Stop polling on any status other than PENDING or PROCESSING.
    - `error` string, nullable, required: Customer-safe failure detail when the job did not complete.
    - `clipCountApplied` integer, nullable, required: The clip count the job runs with after the plan's per-video cap (1 for a Summary or Punch).
    - `clips` ClipItem[], required
      - `clipId` string, required: The id POST /api/v1/publish takes (equal to id).
      - `id` string, required
      - `title` string, nullable, required
      - `clipUrl` string, nullable, required: Publicly fetchable MP4 once rendered.
      - `thumbnailUrl` string, nullable, required
      - `durationSeconds` integer, nullable, required
      - `status` string, required
      - `review` ClipReview, required: What to tell the user before asking them to confirm a publish. Clips with quality-check warnings can still be published by the user's explicit choice; mention the warnings.
        - `qcWarnings` QcWarning[], required: Owner-facing quality-check warnings; empty when the clip passed.
          - `flag` string, required: Stable machine key (e.g. profanity, dead_zone); _other for a flag without specific copy.
          - `label` string, required
          - `detail` string, required
        - `sourceStartSeconds` number, nullable, required: Where the clip starts in the source video, in seconds (null on older clips).
        - `sourceEndSeconds` number, nullable, required: Where the clip ends in the source video, in seconds (null on older clips).
        - `archetype` string, nullable, required: The editorial cut, e.g. top_moments, summary, punch.
        - `captions` 'NONE' | 'PENDING' | 'BURNED_IN' | 'FAILED' | 'null', nullable, required: Caption state.
        - `hook` string, nullable, required: The words spoken in the clip's opening seconds, when recorded.
        - `width` integer, nullable, required: Rendered width in pixels, measured from the file (null when not measured).
        - `height` integer, nullable, required: Rendered height in pixels, measured from the file (null when not measured).
        - `heldForReview` boolean, required: true when an earlier publish attempt left the clip held for content review (publishing answers 403 content_review until it is cleared).

## Other responses

- `401`: The API key did not authenticate. code=key_missing: no Authorization: Bearer epk_... header. code=key_invalid: the key is unknown or revoked. code=key_expired: the key passed its expiry; the user creates a new one in Dashboard → API.
- `402`: REST and MCP need the Pro or Scale plan. reason=subscription: the account has no active subscription (subscribe, or redeem an invite code). reason=plan: the account's plan doesn't include this (API and agent access need Pro or Scale).
- `403`: code=scope (also reason=scope): the API key is read-only and this is a write. code=suspended: the account is suspended. Endpoint-specific refusals document their own reason.
- `404`: Job not found for this account.
- `429`: Too many requests. code=rate_limited: the per-minute limit; wait Retry-After (60) seconds. code=quota_exhausted (with used, limit, resetsAt, retryable: false): the monthly allowance is used up; Retry-After is the seconds until resetsAt — tell the user rather than wait. code=queue_capacity (retryable: true): the render queue is full; retry after Retry-After (180).

---

[API](https://skmtc.dev/everpop/apis/everpop-api.md) · [All operations](https://skmtc.dev/everpop/apis/everpop-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everpop/apis/everpop-api/revisions/1a9fb20867f5?raw)