> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Cast history



## OpenAPI

````yaml /api/openapi.json post /api/v1/cast/generations/search
openapi: 3.0.2
info:
  title: Melius API
  version: '1'
  description: >-
    The Melius REST API. Authenticate with an API key as a bearer token
    (`Authorization: Bearer mel_...`) and select the team to act on with the
    `x-team-id` header. Generations run through the same node + run pipeline as
    the app: create a node on a canvas, start a run, poll the run, then read the
    resulting version asset.
servers:
  - url: https://api.melius.com
security:
  - apiKey: []
    teamId: []
paths:
  /api/v1/cast/generations/search:
    post:
      tags:
        - cast
      summary: Search Cast history
      operationId: cast.history
      parameters: []
      requestBody:
        description: Body
        content:
          application/json:
            schema:
              type: object
              properties:
                pageSize:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 100
                  default: 24
                cursor:
                  type: string
                  minLength: 1
                  maxLength: 4096
                includeCount:
                  type: boolean
                  default: false
                filters:
                  type: object
                  properties:
                    scope:
                      type: string
                      enum:
                        - mine
                        - team
                      default: mine
                    generationId:
                      type: string
                      format: uuid
                    includeReplacements:
                      type: boolean
                    operation:
                      type: string
                      enum:
                        - script
                        - replacement
                  default: {}
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        canvasId:
                          type: string
                          format: uuid
                        createdAt:
                          type: string
                          format: date-time
                        config:
                          type: object
                          properties:
                            operation:
                              type: string
                              enum:
                                - script
                                - replacement
                            replacement:
                              oneOf:
                                - type: object
                                  properties:
                                    sourceAssetId:
                                      type: string
                                      format: uuid
                                    dittoTemplate:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        revision:
                                          type: integer
                                          minimum: 0
                                          exclusiveMinimum: true
                                      required:
                                        - id
                                        - revision
                                    styleId:
                                      type: string
                                      format: uuid
                                      description: >-
                                        A Ditto style to re-render the whole
                                        source video in. Send no replacements
                                        with it.
                                    additionalInstructions:
                                      type: string
                                      maxLength: 2000
                                    sourceRange:
                                      type: object
                                      properties:
                                        startMs:
                                          type: number
                                          minimum: 0
                                        endMs:
                                          type: number
                                          minimum: 0
                                          exclusiveMinimum: true
                                      required:
                                        - startMs
                                        - endMs
                                    modelId:
                                      type: string
                                      minLength: 1
                                      maxLength: 100
                                    resolution:
                                      type: string
                                      enum:
                                        - 480p
                                        - 720p
                                        - 1080p
                                        - 480P
                                        - 768P
                                        - 1080P
                                    audioMode:
                                      type: string
                                      enum:
                                        - original
                                        - mute
                                      default: original
                                    replacements:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          referenceAssetId:
                                            type: string
                                            format: uuid
                                            description: >-
                                              Image asset showing the replacement
                                              appearance for this item.
                                          targetKind:
                                            type: string
                                            enum:
                                              - character
                                              - prop
                                              - background
                                            description: >-
                                              What this reference image replaces in
                                              the source video.
                                          targetDescription:
                                            type: string
                                            maxLength: 1000
                                            description: >-
                                              Optional description identifying the
                                              existing character, prop or background
                                              to replace.
                                          pendingAvatarRenderId:
                                            type: string
                                            format: uuid
                                            description: >-
                                              A custom avatar render of this character
                                              that may still be in progress. The run
                                              waits a few minutes for it and uses its
                                              portrait in place of referenceAssetId if
                                              it finishes in time; otherwise it uses
                                              referenceAssetId.
                                          avatar:
                                            type: object
                                            properties:
                                              kind:
                                                type: string
                                                enum:
                                                  - custom
                                                  - curated
                                                description: >-
                                                  custom for one of the team's Cast
                                                  avatars; curated for a Melius avatar
                                              id:
                                                type: string
                                                format: uuid
                                                description: The avatar's id from GET /ditto/avatars.
                                            required:
                                              - kind
                                              - id
                                            description: >-
                                              The avatar whose image referenceAssetId
                                              is. Prepare takes it in place of
                                              referenceAssetId and returns both; run
                                              checks the avatar still has that image.
                                        required:
                                          - referenceAssetId
                                          - targetKind
                                      maxItems: 30
                                  required:
                                    - sourceAssetId
                                    - audioMode
                                    - replacements
                                - type: object
                                  properties:
                                    sourceAssetId:
                                      type: string
                                      format: uuid
                                    dittoTemplate:
                                      type: object
                                      properties:
                                        id:
                                          type: string
                                          format: uuid
                                        revision:
                                          type: integer
                                          minimum: 0
                                          exclusiveMinimum: true
                                      required:
                                        - id
                                        - revision
                                    styleId:
                                      type: string
                                      format: uuid
                                      description: >-
                                        A Ditto style to re-render the whole
                                        source video in. Send no replacements
                                        with it.
                                    additionalInstructions:
                                      type: string
                                      maxLength: 2000
                                    sourceRange:
                                      type: object
                                      properties:
                                        startMs:
                                          type: number
                                          minimum: 0
                                        endMs:
                                          type: number
                                          minimum: 0
                                          exclusiveMinimum: true
                                      required:
                                        - startMs
                                        - endMs
                                    modelId:
                                      type: string
                                      minLength: 1
                                      maxLength: 100
                                    resolution:
                                      type: string
                                      enum:
                                        - 480p
                                        - 720p
                                        - 1080p
                                        - 480P
                                        - 768P
                                        - 1080P
                                    audioMode:
                                      type: string
                                      enum:
                                        - original
                                        - mute
                                      default: original
                                    referenceAssetId:
                                      type: string
                                      format: uuid
                                      description: >-
                                        Image asset showing the replacement
                                        appearance for this item.
                                    targetKind:
                                      type: string
                                      enum:
                                        - character
                                        - prop
                                        - background
                                      description: >-
                                        What this reference image replaces in
                                        the source video.
                                    targetDescription:
                                      type: string
                                      maxLength: 1000
                                      description: >-
                                        Optional description identifying the
                                        existing character, prop or background
                                        to replace.
                                    pendingAvatarRenderId:
                                      type: string
                                      format: uuid
                                      description: >-
                                        A custom avatar render of this character
                                        that may still be in progress. The run
                                        waits a few minutes for it and uses its
                                        portrait in place of referenceAssetId if
                                        it finishes in time; otherwise it uses
                                        referenceAssetId.
                                  required:
                                    - sourceAssetId
                                    - audioMode
                                    - referenceAssetId
                                    - targetKind
                            sections:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  title:
                                    type: string
                                  text:
                                    type: string
                                  action:
                                    type: string
                                  kind:
                                    type: string
                                    enum:
                                      - action
                                  cutaway:
                                    type: boolean
                                    enum:
                                      - true
                                  seconds:
                                    type: integer
                                    minimum: 1
                                    maximum: 8
                                  speakerId:
                                    type: string
                                  continues:
                                    type: boolean
                                  inShot:
                                    type: array
                                    items:
                                      type: string
                                  scene:
                                    type: string
                                required:
                                  - id
                                  - text
                            requestedSeconds:
                              type: number
                              minimum: 0
                              exclusiveMinimum: true
                            creationSettings:
                              type: object
                              properties:
                                videoStyle:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      enum:
                                        - auto
                                        - self-filmed
                                        - produced
                                        - drama
                                        - vlog
                                        - podcast
                                        - unboxing
                                        - tutorial
                                        - announcement
                                        - explainer
                                        - founder-story
                                        - before-after
                                        - corporate-training
                                        - storytime
                                        - comment-reply
                                        - streamer-reaction
                                        - animated-3d
                                        - street-interview
                                    version:
                                      type: number
                                      enum:
                                        - 1
                                  required:
                                    - id
                                    - version
                                speech:
                                  type: string
                                  enum:
                                    - on-screen
                                    - narration
                                visuals:
                                  type: string
                                  enum:
                                    - auto
                                    - 'on'
                                    - 'off'
                                  description: >-
                                    Auto chooses useful supporting visuals from
                                    the script, actions and props across video
                                    styles, and may keep generated footage
                                    alone. Off skips added visuals. On remains
                                    accepted for compatibility. Subtitles are
                                    separate; generation eligibility still
                                    applies.
                                pronunciations:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      word:
                                        type: string
                                        minLength: 1
                                        maxLength: 200
                                      pronunciation:
                                        type: string
                                        minLength: 1
                                        maxLength: 200
                                    required:
                                      - word
                                      - pronunciation
                                  maxItems: 50
                                  description: >-
                                    Confirmed spoken spellings, e.g.
                                    [{"word":"Emmaus","pronunciation":"ee-may-us"}].
                                    Applied to speech only; keep the original
                                    spelling in the script and visual
                                    directions.
                              required:
                                - videoStyle
                                - speech
                            scriptTemplate:
                              type: object
                              properties:
                                id:
                                  type: string
                                  format: uuid
                                revision:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                source:
                                  type: string
                                  enum:
                                    - static
                                    - database
                              required:
                                - id
                                - revision
                                - source
                            avatarId:
                              type: string
                            voiceId:
                              type: string
                            customVoiceId:
                              type: string
                            voiceName:
                              type: string
                            autoVoice:
                              type: boolean
                            aspectRatio:
                              type: string
                            platformId:
                              type: string
                            direction:
                              type: string
                            tone:
                              type: string
                            customAvatarId:
                              type: string
                            presetAvatarId:
                              type: string
                            elementId:
                              type: string
                            elementVersionId:
                              type: string
                            elementReferenceAssetId:
                              type: string
                            elementReferenceImageLayout:
                              type: string
                              enum:
                                - portrait-three-view
                                - landscape-four-view
                                - landscape-six-view
                            backgroundId:
                              type: string
                            productAssetId:
                              type: string
                            productRole:
                              type: string
                              enum:
                                - in-hand
                            comment:
                              type: object
                              properties:
                                author:
                                  type: string
                                  minLength: 1
                                  maxLength: 60
                                text:
                                  type: string
                                  minLength: 1
                                  maxLength: 300
                              required:
                                - text
                              additionalProperties: false
                            products:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  assetId:
                                    type: string
                                  elementId:
                                    type: string
                                  elementVersionId:
                                    type: string
                                required:
                                  - id
                                  - assetId
                            avatars:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: string
                                  customAvatarId:
                                    type: string
                                  presetAvatarId:
                                    type: string
                                  elementId:
                                    type: string
                                  elementVersionId:
                                    type: string
                                  elementReferenceAssetId:
                                    type: string
                                  elementReferenceImageLayout:
                                    type: string
                                    enum:
                                      - portrait-three-view
                                      - landscape-four-view
                                      - landscape-six-view
                                  voiceId:
                                    type: string
                                  customVoiceId:
                                    type: string
                                required:
                                  - id
                            treatment:
                              type: string
                              enum:
                                - self-filmed
                                - produced
                                - vlog
                            starterId:
                              type: string
                            subtitles:
                              type: object
                              properties:
                                preset:
                                  type: string
                                  enum:
                                    - simple
                                    - plain
                                    - beans
                                    - corpo
                                    - boo
                                    - shadeplay
                                    - casper
                                    - capri
                                    - lowkey
                                    - vinta
                                    - diego
                                    - ali
                                    - slay
                                    - kitty
                                    - hustle
                                    - karl
                                    - sprout
                                    - flex
                                    - mint
                                    - rizz
                                    - vegas
                                    - glass
                                    - whisper
                                    - glide2
                                    - fusion
                                    - glide
                                    - terminal
                                    - handwritten
                                language:
                                  type: string
                                position:
                                  type: string
                                  enum:
                                    - top
                                    - center
                                    - bottom
                                textCustomizations:
                                  type: object
                                  properties:
                                    baseline:
                                      type: object
                                      properties:
                                        font:
                                          type: string
                                        weight:
                                          type: integer
                                        color:
                                          type: string
                                    highlighted:
                                      type: object
                                      properties:
                                        font:
                                          type: string
                                        weight:
                                          type: integer
                                        color:
                                          type: string
                              required:
                                - preset
                            engine:
                              type: string
                              enum:
                                - boreal
                                - heygen
                                - seedance
                                - seedance-2
                                - kling-3-turbo
                                - omni-1.1-flash
                                - minimax-h3-max
                                - wan-3
                            resolution:
                              oneOf:
                                - type: string
                                  enum:
                                    - 360p
                                    - 480p
                                    - 540p
                                    - 580p
                                    - 720p
                                    - 480P
                                    - 768P
                                    - 1080P
                                    - 1080p
                                    - 1440p
                                    - 2160p
                                    - 4k
                                    - 0.5K
                                    - 1K
                                    - 2K
                                    - 4K
                                    - 1k
                                    - 2k
                                - type: string
                            analytics:
                              type: object
                              properties:
                                entrySurface:
                                  type: string
                                  enum:
                                    - cast
                                    - cast-mcp
                                    - canvas-agent
                                agent:
                                  type: object
                                  properties:
                                    sessionId:
                                      type: string
                                      format: uuid
                                    messageId:
                                      type: string
                                      format: uuid
                                    canvasId:
                                      type: string
                                      format: uuid
                                    approval:
                                      type: string
                                      enum:
                                        - member
                                        - auto_run
                                  required:
                                    - sessionId
                                visitId:
                                  type: string
                                  format: uuid
                                workId:
                                  type: string
                                  format: uuid
                                planAtEvent:
                                  type: string
                                  enum:
                                    - TIER_0
                                    - TIER_1
                                    - TIER_2
                                    - TIER_3
                                    - TEAM
                                    - TIER_4
                                engine:
                                  type: string
                                  enum:
                                    - boreal
                                    - heygen
                                    - seedance
                                    - seedance-2
                                    - kling-3-turbo
                                    - omni-1.1-flash
                                    - minimax-h3-max
                                    - wan-3
                                avatarId:
                                  type: string
                                avatarKind:
                                  type: string
                                  enum:
                                    - preset
                                    - custom
                                    - curated
                                    - element
                                backgroundKind:
                                  type: string
                                  enum:
                                    - auto
                                    - preset_recording
                                    - plate
                                    - curated_plate
                                backgroundId:
                                  type: string
                                  format: uuid
                                hasProp:
                                  type: boolean
                                hasTone:
                                  type: boolean
                                treatment:
                                  type: string
                                  enum:
                                    - self-filmed
                                    - produced
                                    - vlog
                                aspectRatio:
                                  type: string
                                voiceKind:
                                  type: string
                                  enum:
                                    - default
                                    - stock
                                    - cloned
                                    - auto
                                resolution:
                                  oneOf:
                                    - type: string
                                      enum:
                                        - 360p
                                        - 480p
                                        - 540p
                                        - 580p
                                        - 720p
                                        - 480P
                                        - 768P
                                        - 1080P
                                        - 1080p
                                        - 1440p
                                        - 2160p
                                        - 4k
                                        - 0.5K
                                        - 1K
                                        - 2K
                                        - 4K
                                        - 1k
                                        - 2k
                                    - type: string
                                hasSubtitles:
                                  type: boolean
                                subtitlePreset:
                                  type: string
                                  maxLength: 60
                                beatCount:
                                  type: integer
                                  minimum: 0
                                avatarCount:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                partCount:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                voiceRoute:
                                  type: string
                                  enum:
                                    - track
                                    - reference
                                    - sample
                                    - auto
                                placeImageCount:
                                  type: integer
                                  minimum: 0
                                scriptSeconds:
                                  type: integer
                                  minimum: 0
                                creditCost:
                                  type: integer
                                  nullable: true
                                  minimum: 0
                                takeNumber:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                attemptNumberWithinWork:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                scriptSource:
                                  type: string
                                  enum:
                                    - starter
                                    - written
                                    - past_script
                                scriptEntryMethod:
                                  type: string
                                  enum:
                                    - typed
                                    - pasted
                                    - file_text
                                    - file_markdown
                                    - file_docx
                                    - file_pdf
                                    - manual_section
                                    - starter
                                    - history_use
                                    - history_open
                                    - remix
                                scriptOrigin:
                                  type: string
                                  enum:
                                    - starter
                                    - bring_your_own
                                    - unknown
                                starterId:
                                  type: string
                                  maxLength: 80
                                rootWorkId:
                                  type: string
                                  format: uuid
                                sourceRunId:
                                  type: string
                                  format: uuid
                                publicSourceGenerationId:
                                  type: string
                                  format: uuid
                                campaign:
                                  type: object
                                  properties:
                                    source:
                                      type: string
                                      maxLength: 80
                                    medium:
                                      type: string
                                      enum:
                                        - email
                                    name:
                                      type: string
                                      maxLength: 80
                                    content:
                                      type: string
                                      maxLength: 80
                                    landedAt:
                                      type: string
                                      format: date-time
                                  required:
                                    - source
                                    - name
                                    - landedAt
                                promo:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                      pattern: ^[a-z0-9][a-z0-9._-]{0,79}$
                                    surface:
                                      type: string
                                      pattern: ^[a-z0-9][a-z0-9._-]{0,79}$
                                    clickedAt:
                                      type: string
                                      format: date-time
                                    sessionId:
                                      type: string
                                      format: uuid
                                  required:
                                    - id
                                    - surface
                                    - clickedAt
                                entryPoint:
                                  type: string
                                  enum:
                                    - sidebar
                                    - home
                                    - onboarding
                                    - share_link
                                    - example_link
                                    - canvas
                                    - guest_draft
                                    - offers_menu
                                    - direct
                                exploreVideoId:
                                  type: string
                                  format: uuid
                                exploreVideoRevision:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                              required:
                                - visitId
                                - workId
                                - avatarId
                                - hasProp
                                - hasTone
                                - aspectRatio
                                - beatCount
                                - scriptSeconds
                                - creditCost
                                - takeNumber
                                - attemptNumberWithinWork
                          additionalProperties: true
                        createdBy:
                          type: object
                          nullable: true
                          properties:
                            id:
                              type: string
                              format: uuid
                            name:
                              type: string
                            avatarUrl:
                              type: string
                              nullable: true
                          required:
                            - id
                            - name
                            - avatarUrl
                        bulkNodeRunId:
                          type: string
                          nullable: true
                          format: uuid
                        status:
                          type: string
                          enum:
                            - generating
                            - ready
                            - failed
                        failureMessage:
                          type: string
                          nullable: true
                        subtitlesFailureMessage:
                          type: string
                          nullable: true
                        commentFailureMessage:
                          type: string
                          nullable: true
                        videoUrl:
                          type: string
                          nullable: true
                        posterUrl:
                          type: string
                          nullable: true
                        videoWidth:
                          type: integer
                          nullable: true
                          minimum: 0
                          exclusiveMinimum: true
                        videoHeight:
                          type: integer
                          nullable: true
                          minimum: 0
                          exclusiveMinimum: true
                        title:
                          type: string
                          nullable: true
                        assetId:
                          type: string
                          nullable: true
                          format: uuid
                        durationMs:
                          type: number
                          nullable: true
                          minimum: 0
                        savedToFiles:
                          type: boolean
                        myFeedback:
                          type: string
                          nullable: true
                          enum:
                            - positive
                            - negative
                            - null
                        upscale:
                          type: object
                          nullable: true
                          properties:
                            model:
                              type: string
                            modelName:
                              type: string
                            source:
                              type: object
                              properties:
                                width:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                                height:
                                  type: integer
                                  minimum: 0
                                  exclusiveMinimum: true
                              required:
                                - width
                                - height
                            options:
                              type: array
                              items:
                                type: object
                                properties:
                                  resolution:
                                    type: string
                                    enum:
                                      - 1080p
                                      - 2k
                                      - 4k
                                  creditCost:
                                    type: integer
                                    minimum: 0
                                  status:
                                    type: string
                                    enum:
                                      - available
                                      - upscaling
                                      - ready
                                      - failed
                                  failureMessage:
                                    type: string
                                    nullable: true
                                  generationId:
                                    type: string
                                    nullable: true
                                    format: uuid
                                required:
                                  - resolution
                                  - creditCost
                                  - status
                                  - failureMessage
                          required:
                            - model
                            - modelName
                            - source
                            - options
                        upscaledFrom:
                          type: object
                          nullable: true
                          properties:
                            generationId:
                              type: string
                              format: uuid
                            resolution:
                              type: string
                              enum:
                                - 1080p
                                - 2k
                                - 4k
                            model:
                              type: string
                            modelName:
                              type: string
                          required:
                            - generationId
                            - resolution
                            - model
                            - modelName
                        addSubtitles:
                          type: object
                          nullable: true
                          properties:
                            creditCost:
                              type: integer
                              minimum: 0
                          required:
                            - creditCost
                        subtitledFrom:
                          type: object
                          nullable: true
                          properties:
                            generationId:
                              type: string
                              format: uuid
                          required:
                            - generationId
                      required:
                        - id
                        - canvasId
                        - createdAt
                        - config
                  pageSize:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  count:
                    type: integer
                    nullable: true
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  hasMore:
                    type: boolean
                  nextCursor:
                    type: string
                    nullable: true
                    minLength: 1
                    maxLength: 4096
                required:
                  - data
                  - pageSize
                  - count
                  - hasMore
                  - nextCursor
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
        '401':
          description: Missing, invalid, expired, or revoked API key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                required:
                  - statusCode
                  - message
        '403':
          description: The API key's user is not a member of the requested team.
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                required:
                  - statusCode
                  - message
        '429':
          description: Rate limit reached — retry after the `Retry-After` header.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                properties:
                  statusCode:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                  retryAfterSeconds:
                    type: integer
                required:
                  - statusCode
                  - message
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'A Melius API key (`mel_...`), sent as `Authorization: Bearer <key>`.'
    teamId:
      type: apiKey
      in: header
      name: x-team-id
      description: The team (workspace) to act on. Defaults to the key's team when omitted.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.