Skip to content
MediuxDocs

Retrieve a List

GET/lists/{id}

Returns a Public List: its header and, for a Media or Game List, every title with its top-level poster; an Asset List returns its images.

kind is assetList, mediaList or gameList. A Media or Game List holds up to 500 titles, with or without artwork (titles[]: entity, position, poster, choiceCount, updatedAt); a title's Season, Episode and other choices are on /lists/{id}/titles/{family}/{entity}. An Asset List returns its images (at most 1,000 and, after one Set add, at most 3,499) as full Asset objects in items, in List order. owner is {id, username}; subscriberCount is embedded and refreshes hourly, and Like counts are not served. Private, unknown or deleted Lists return 404 (stored at the edge for 24 hours, never by the browser). Responses are stored but revalidated with the ETag.

Path parameters

  • id string required

    The List's ID (a lowercase UUID).

    pattern

Responses

200 The List.

Headers

  • ETag string

    Validator, weak (W/) when the response is compressed. Send it back unchanged as If-None-Match to receive 304.

  • Cache-Control string

    Browser caching policy.

    "public, no-cache"
  • data object
    Show options

    One of

    kind = "assetList"
    • kind string
      "assetList"
    • id string (uuid)
    • name string
    • description string | null
    • owner object
      Show child attributes
      • id string (uuid)
      • username string
        min length 1
    • itemCount integer
      min 0
    • subscriberCount integer
      min 0
    • createdAt string

      ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

      pattern
    • updatedAt string

      ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

      pattern
    • items array of object
      Show item attributes
      • id string (uuid)
      • extension string
        pattern ^[a-z0-9]{2,5}$
      • slot string
        "poster""backdrop""logo""squareArt""titlecard""thumb""cover""hero""wideCover""background""squareCover""icon"
      • entity object
        Show child attributes
        • kind string
        • id integer
          positive
      • language string | null

        ISO 639-1 code; xx is textless.

        pattern ^[a-z]{2}$
      • edition string | null
        "theatricalCut""directorsCut""extendedCut""unratedCut""imaxVersion""criterionEdition""finalCut""fanEdit""producersCut""alternateColorGrading"
      • width integer
        positive
      • height integer
        positive
      • fileSize integer
        min 0
      • set object | null
        Show child attributes
        • kind string
          "showSet""movieSet""collectionSet""gameSet""talentSet""brandSet""categorySet"
        • id integer
          positive
      • creator object
        Show child attributes
        • id string (uuid)
        • username string
          min length 1
      • createdAt string

        ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

        pattern
      • updatedAt string

        ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

        pattern
    Option 2
    • kind string
      "mediaList""gameList"
    • id string (uuid)
    • name string
    • description string | null
    • owner object
      Show child attributes
      • id string (uuid)
      • username string
        min length 1
    • itemCount integer
      min 0
    • subscriberCount integer
      min 0
    • createdAt string

      ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

      pattern
    • updatedAt string

      ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

      pattern
    • titles array of object
      Show item attributes
      • entity object
        Show child attributes
        • id integer
          positive
        • title string
        • year integer | null
          min 1max 9999
        • kind string
          "show""season""episode""movie""collection""person""network""company""category""game"
      • position integer
        min 0
      • poster object | null
        Show child attributes
        • id string (uuid)
        • extension string
          pattern ^[a-z0-9]{2,5}$
        • language string | null

          ISO 639-1 code; xx is textless.

          pattern ^[a-z]{2}$
        • edition string | null
          "theatricalCut""directorsCut""extendedCut""unratedCut""imaxVersion""criterionEdition""finalCut""fanEdit""producersCut""alternateColorGrading"
        • width integer
          positive
        • height integer
          positive
        • fileSize integer
          min 0
        • set object | null
          Show child attributes
          • kind string
            "showSet""movieSet""collectionSet""gameSet""talentSet""brandSet""categorySet"
          • id integer
            positive
        • creator object
          Show child attributes
          • id string (uuid)
          • username string
            min length 1
        • createdAt string

          ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

          pattern
        • updatedAt string

          ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

          pattern
      • choiceCount integer
        min 0
      • updatedAt string

        ISO 8601 UTC instant with milliseconds, such as 2026-11-14T15:03:02.000Z.

        pattern
304 Not modified. The If-None-Match validator still matches; no body.
400 The path is not a valid route, or the request carried a query string or body.

Headers

  • Cache-Control string

    Browser caching policy.

    "no-store"
  • data any | null

    Always null on an error.

  • error object

    Why the request failed.

    Show child attributes
    • code string

      Stable dotted camelCase code such as resource.gone. Branch on this, not on message.

    • message string

      Short explanation for people. Wording can change.

      min length 1max length 256
    • requestId string

      The Cloudflare ray ID. Absent on Snippet and WAF errors and on cached 404, 410 and 503 responses, which carry it only in cf-ray.

      min length 1
    • docs string (uri)

      Link to this code's entry in the error catalogue.

    • details map of string | number | boolean | array of string | null

      Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

    • issues array of object

      Per-field validation failures, when any.

      max 50 items
      Show item attributes
      • code string

        Stable code for this field failure. Branch on this.

        min length 1
      • message string

        Short human-readable description of this field failure.

        min length 1
      • path array of string

        Path to the failing field, for example ["items", 2, "slot"].

      • details map of string | number | boolean | array of string | null

        Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

404 The resource does not exist or is not public.

Headers

  • Cache-Control string

    Browser caching policy.

    "no-store"
  • data any | null

    Always null on an error.

  • error object

    Why the request failed.

    Show child attributes
    • code string

      Stable dotted camelCase code such as resource.gone. Branch on this, not on message.

    • message string

      Short explanation for people. Wording can change.

      min length 1max length 256
    • requestId string

      The Cloudflare ray ID. Absent on Snippet and WAF errors and on cached 404, 410 and 503 responses, which carry it only in cf-ray.

      min length 1
    • docs string (uri)

      Link to this code's entry in the error catalogue.

    • details map of string | number | boolean | array of string | null

      Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

    • issues array of object

      Per-field validation failures, when any.

      max 50 items
      Show item attributes
      • code string

        Stable code for this field failure. Branch on this.

        min length 1
      • message string

        Short human-readable description of this field failure.

        min length 1
      • path array of string

        Path to the failing field, for example ["items", 2, "slot"].

      • details map of string | number | boolean | array of string | null

        Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

405 Only GET, HEAD and OPTIONS are supported.

Headers

  • Cache-Control string

    Browser caching policy.

    "no-store"
  • data any | null

    Always null on an error.

  • error object

    Why the request failed.

    Show child attributes
    • code string

      Stable dotted camelCase code such as resource.gone. Branch on this, not on message.

    • message string

      Short explanation for people. Wording can change.

      min length 1max length 256
    • requestId string

      The Cloudflare ray ID. Absent on Snippet and WAF errors and on cached 404, 410 and 503 responses, which carry it only in cf-ray.

      min length 1
    • docs string (uri)

      Link to this code's entry in the error catalogue.

    • details map of string | number | boolean | array of string | null

      Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

    • issues array of object

      Per-field validation failures, when any.

      max 50 items
      Show item attributes
      • code string

        Stable code for this field failure. Branch on this.

        min length 1
      • message string

        Short human-readable description of this field failure.

        min length 1
      • path array of string

        Path to the failing field, for example ["items", 2, "slot"].

      • details map of string | number | boolean | array of string | null

        Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

429 Too many cache misses from this address. Retry after the Retry-After delay.

Headers

  • Cache-Control string

    Browser caching policy.

    "no-store"
  • Retry-After string

    Seconds to wait before trying again.

    pattern ^\d+$
  • data any | null

    Always null on an error.

  • error object

    Why the request failed.

    Show child attributes
    • code string

      Stable dotted camelCase code such as resource.gone. Branch on this, not on message.

    • message string

      Short explanation for people. Wording can change.

      min length 1max length 256
    • requestId string

      The Cloudflare ray ID. Absent on Snippet and WAF errors and on cached 404, 410 and 503 responses, which carry it only in cf-ray.

      min length 1
    • docs string (uri)

      Link to this code's entry in the error catalogue.

    • details map of string | number | boolean | array of string | null

      Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

    • issues array of object

      Per-field validation failures, when any.

      max 50 items
      Show item attributes
      • code string

        Stable code for this field failure. Branch on this.

        min length 1
      • message string

        Short human-readable description of this field failure.

        min length 1
      • path array of string

        Path to the failing field, for example ["items", 2, "slot"].

      • details map of string | number | boolean | array of string | null

        Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

503 Temporarily unavailable. Retry after the Retry-After delay.

Headers

  • Cache-Control string

    Browser caching policy.

    "no-store"
  • Retry-After string

    Seconds to wait before trying again.

    pattern ^\d+$
  • data any | null

    Always null on an error.

  • error object

    Why the request failed.

    Show child attributes
    • code string

      Stable dotted camelCase code such as resource.gone. Branch on this, not on message.

    • message string

      Short explanation for people. Wording can change.

      min length 1max length 256
    • requestId string

      The Cloudflare ray ID. Absent on Snippet and WAF errors and on cached 404, 410 and 503 responses, which carry it only in cf-ray.

      min length 1
    • docs string (uri)

      Link to this code's entry in the error catalogue.

    • details map of string | number | boolean | array of string | null

      Constraints that apply to the failure, such as byte limits, dimensions or allowed types.

    • issues array of object

      Per-field validation failures, when any.

      max 50 items
      Show item attributes
      • code string

        Stable code for this field failure. Branch on this.

        min length 1
      • message string

        Short human-readable description of this field failure.

        min length 1
      • path array of string

        Path to the failing field, for example ["items", 2, "slot"].

      • details map of string | number | boolean | array of string | null

        Constraints that apply to the failure, such as byte limits, dimensions or allowed types.