TranscriptionListResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/arcmira/json-schema/arcmira-transcription-list-response-schema.json",
  "title": "TranscriptionListResponse",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/arcmira-transcriptions-api-openapi.yml#/components/schemas/TranscriptionListResponse",
  "type": "object",
  "properties": {
    "requests": {
      "type": "array",
      "items": {
        "allOf": [
          {
            "$ref": "#/$defs/TranscriptionJob"
          },
          {
            "type": "object",
            "properties": {
              "title": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Video title for display. Null when unknown."
              }
            },
            "required": [
              "title"
            ]
          }
        ],
        "description": "A Premium transcript job with its processing state, charge and URL for reading the transcript again."
      },
      "description": "Your requests in descending creation time and id order, up to the requested limit."
    },
    "has_more": {
      "type": "boolean",
      "description": "True when another page exists in this traversal."
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Signed continuation for the same filter, limit and credential; null on the last page."
    }
  },
  "required": [
    "requests",
    "has_more",
    "next_cursor"
  ],
  "$defs": {
    "TranscriptionJob": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Transcription request id (UUID)."
        },
        "video_id": {
          "type": "string",
          "description": "YouTube video id (11 characters)."
        },
        "state": {
          "type": "string",
          "enum": [
            "pending",
            "ready",
            "failed",
            "refunded"
          ],
          "description": "Coarse outcome: pending until the Premium transcript is servable (ready), the job failed, or it was refunded."
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "downloading",
            "transcribing",
            "analyzing",
            "complete",
            "failed",
            "refund_pending",
            "refunded"
          ],
          "description": "Request status. Values: queued (accepted; audio download not started), downloading (fetching the video audio), transcribing (premium speech-to-text is running), analyzing (entity/commercial analysis is running), complete (premium transcript is servable via GET /v1/transcripts/{video_id}), failed (rejected intent, or a legacy request needing accounting review), refund_pending (refund transaction must still complete), refunded (terminal failure; the charge was returned and the unlock this request granted was revoked)."
        },
        "stage": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "queued",
            "transcribing",
            "analyzing",
            null
          ],
          "description": "User-facing stage: downloading folds into transcribing. Values: queued (waiting to start), transcribing (downloading or transcribing), analyzing (analysis running). Null for terminal statuses and refund_pending."
        },
        "charge": {
          "type": "object",
          "properties": {
            "unit": {
              "type": "string",
              "enum": [
                "credits"
              ]
            },
            "amount": {
              "type": "number",
              "description": "Credits this job charged. 0 when a prior unlock made it free."
            },
            "from": {
              "type": "string",
              "enum": [
                "included",
                "on_demand",
                "mixed"
              ],
              "description": "Where the credits came from. included is the plan's credits, on_demand is the on-demand budget, mixed is both. Present once the job is funded."
            }
          },
          "required": [
            "unit",
            "amount"
          ],
          "description": "What the job charged. Absent only on legacy requests."
        },
        "eta_seconds": {
          "type": "integer",
          "description": "Estimated seconds until completion, re-derived from live pipeline telemetry on every poll. Only present while the request is in flight; absent on refund_pending, which has no completion ETA."
        },
        "next_poll_seconds": {
          "type": "integer",
          "description": "Seconds to sleep before the next poll (also sent as the Retry-After header). Only present while the request is in flight."
        },
        "error": {
          "type": "string",
          "description": "Failure reason. Only present when state is failed or refunded, or status is refund_pending."
        },
        "refunded": {
          "type": "boolean",
          "description": "True when the charge was returned. Only present when state is failed or refunded, or status is refund_pending (false until the refund lands)."
        },
        "created_at": {
          "type": "string",
          "description": "When the request was submitted."
        },
        "completed_at": {
          "type": "string",
          "description": "When the request reached a terminal status. Absent while in flight."
        },
        "status_url": {
          "type": "string",
          "description": "Absolute URL to read again for this job: GET /v1/transcripts/{video_id}?quality=premium, which answers 202 while it transcribes, 200 ready once it is done, and 200 failed if it failed."
        }
      },
      "required": [
        "id",
        "video_id",
        "state",
        "status",
        "stage",
        "created_at",
        "status_url"
      ],
      "description": "A Premium transcript job with its processing state, charge and URL for reading the transcript again."
    }
  }
}