# Retrieve an Asset

> Retrieve an Asset and its streaming, static, poster, and timeline outputs.

```json
{
  "path": "/assets/{assetId}",
  "method": "get",
  "schema": {
    "description": "Retrieve an Asset and its streaming, static, poster, and timeline outputs.",
    "operationId": "getAsset",
    "parameters": [
      {
        "in": "path",
        "name": "assetId",
        "required": true,
        "schema": {
          "type": "string"
        }
      }
    ],
    "responses": {
      "200": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/AssetResponse",
              "examples": [
                {
                  "data": {
                    "can_add_static_renditions": true,
                    "created_at": "2026-09-14T12:00:00Z",
                    "expires_at": "2026-09-15T12:01:00Z",
                    "id": "ast_example",
                    "max_resolution": "1080p",
                    "metadata": {},
                    "min_resolution": "auto",
                    "playback_path": "assets/ast_example/manifest.m3u8",
                    "playback_ready": true,
                    "playback_ready_at": "2026-09-14T12:00:10Z",
                    "preview_enabled": true,
                    "preview_url": "https://stream.chunkify.dev/ast_example.m3u8",
                    "ready_at": "2026-09-14T12:01:00Z",
                    "source_metadata": {
                      "audio_bitrate": 128000,
                      "audio_codec": "aac",
                      "audio_samplerate": 48000,
                      "duration": 120,
                      "height": 1080,
                      "size": 12000000,
                      "video_bitrate": 800000,
                      "video_codec": "h264",
                      "video_framerate": 29.97,
                      "width": 1920
                    },
                    "status": "ready",
                    "storage_id": "stor_example",
                    "title": "",
                    "updated_at": "2026-09-14T12:01:00Z",
                    "workflow_id": null,
                    "workflow_revision": null
                  },
                  "status": "success"
                }
              ]
            }
          }
        },
        "description": "Retrieve an Asset"
      },
      "400": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorValidation"
            }
          }
        },
        "description": "Validation error"
      },
      "401": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorAuthentication"
            }
          }
        },
        "description": "Authentication error"
      },
      "403": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorForbidden"
            }
          }
        },
        "description": "Forbidden error"
      },
      "404": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorNotFound"
            }
          }
        },
        "description": "NotFound error"
      },
      "409": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorConflict"
            }
          }
        },
        "description": "Conflict error"
      },
      "429": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorTooManyRequests"
            }
          }
        },
        "description": "TooManyRequests error"
      },
      "503": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ResponseErrorServiceUnavailable"
            }
          }
        },
        "description": "ServiceUnavailable error"
      }
    },
    "security": [
      {
        "ProjectAccessToken": []
      }
    ],
    "summary": "Retrieve an Asset",
    "tags": [
      "Assets"
    ],
    "x-codeSamples": [
      {
        "lang": "typescript",
        "source": "import Chunkify from '@chunkify/chunkify';\n\nconst client = new Chunkify({\n  projectAccessToken: 'My Project Access Token',\n});\n\nconst asset = await client.assets.retrieve('ast_example');\n\nconsole.log(asset);"
      },
      {
        "lang": "python",
        "source": "from chunkify import Chunkify\n\nclient = Chunkify(\n    project_access_token=\"My Project Access Token\",\n)\n\nasset = client.assets.retrieve(\"ast_example\")\nprint(asset)"
      },
      {
        "lang": "php",
        "source": "\u003c?php\n\nuse Chunkify\\Client;\n\n$client = new Client(\n    projectAccessToken: 'My Project Access Token',\n);\n\n$asset = $client-\u003eassets-\u003eretrieve('ast_example');\n\nvar_dump($asset);"
      },
      {
        "lang": "golang",
        "source": "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/chunkifydev/chunkify-go\"\n\t\"github.com/chunkifydev/chunkify-go/option\"\n)\n\nfunc main() {\n\tclient := chunkify.NewClient(\n\t\toption.WithProjectAccessToken(\"My Project Access Token\"),\n\t)\n\tasset, err := client.Assets.Get(context.TODO(), \"ast_example\")\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", asset)\n}\n"
      }
    ]
  }
}
```



```json #/components/schemas/ResponseErrorNotFound
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 404,
          "description": "Code is the HTTP status code",
          "examples": [
            404
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Ressource not found"
          ],
          "type": "string"
        },
        "type": {
          "const": "NotFoundError",
          "description": "Type indicates the error category",
          "enum": [
            "NotFoundError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorConflict
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 409,
          "description": "Code is the HTTP status code",
          "examples": [
            409
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "source_unavailable: the original video is no longer accessible"
          ],
          "type": "string"
        },
        "type": {
          "const": "ConflictError",
          "description": "Type indicates the error category",
          "enum": [
            "ConflictError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorTooManyRequests
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 429,
          "description": "Code is the HTTP status code",
          "examples": [
            429
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Rate limit exceeded"
          ],
          "type": "string"
        },
        "type": {
          "const": "TooManyRequestsError",
          "description": "Type indicates the error category",
          "enum": [
            "TooManyRequestsError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorServiceUnavailable
{
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 503,
          "description": "Code is the HTTP status code",
          "examples": [
            503
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "The service is temporarily unavailable; retry the request"
          ],
          "type": "string"
        },
        "type": {
          "const": "ServiceUnavailableError",
          "description": "Type indicates the error category",
          "enum": [
            "ServiceUnavailableError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```



```json #/components/schemas/AssetResponse
{
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Asset"
    },
    "status": {
      "const": "success",
      "type": "string"
    }
  },
  "required": [
    "status",
    "data"
  ],
  "type": "object"
}
```



```json #/components/schemas/Asset
{
  "properties": {
    "can_add_static_renditions": {
      "description": "Whether the Asset can accept new static rendition requests. Creation can still fail if the original video is no longer accessible.",
      "type": "boolean"
    },
    "cdn_url": {
      "description": "Unsigned CDN URL of the HLS master playlist. Available when playback_ready is true and Storage has a CDN URL.",
      "format": "uri",
      "type": "string"
    },
    "created_at": {
      "description": "When the Asset was created.",
      "format": "date-time",
      "type": "string"
    },
    "created_by_token_id": {
      "description": "CreatedByTokenId specifies the Project token used to create the resource. It remains set after the token is revoked.\nOmitted for dashboard requests, MCP OAuth connections, Workflow actions, and unknown creators.",
      "examples": [
        "tok_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "created_by_user_id": {
      "description": "CreatedByUserId specifies the team member who created the resource.\nOmitted for Workflow actions, unknown creators, and deleted accounts.",
      "examples": [
        "u_2G6MJiNz71bHQGNzGwKx5cJwPFS"
      ],
      "type": "string"
    },
    "created_via": {
      "$ref": "#/components/schemas/CreatedVia"
    },
    "error": {
      "$ref": "#/components/schemas/AssetError"
    },
    "expires_at": {
      "description": "When managed outputs expire, 24 hours after readiness. Omitted for customer-connected Storage.",
      "format": "date-time",
      "type": "string"
    },
    "id": {
      "description": "Unique Asset ID.",
      "type": "string"
    },
    "max_resolution": {
      "description": "Maximum streaming resolution selected at creation. Does not limit static renditions.",
      "enum": [
        "1080p",
        "2160p"
      ],
      "type": "string"
    },
    "metadata": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "String metadata attached to the Asset.",
      "examples": [
        {
          "key": "value",
          "key2": "value2"
        }
      ],
      "type": "object"
    },
    "min_resolution": {
      "description": "Minimum streaming resolution selected at creation. auto means no minimum; smaller sources are not upscaled.",
      "enum": [
        "auto",
        "240p",
        "360p",
        "540p",
        "720p",
        "1080p",
        "1440p",
        "2160p"
      ],
      "type": "string"
    },
    "playback_path": {
      "description": "Path of the HLS master playlist in Storage. Available when playback_ready is true.",
      "type": "string"
    },
    "playback_ready": {
      "description": "Whether HLS playback is available, including while the Asset is preparing.",
      "type": "boolean"
    },
    "playback_ready_at": {
      "description": "When HLS playback first became available.",
      "format": "date-time",
      "type": "string"
    },
    "poster": {
      "$ref": "#/components/schemas/AssetPoster",
      "description": "Poster image, available once generated."
    },
    "preview_enabled": {
      "description": "Allow public preview access without an API token. Does not control CDN or static download access. Disabling it does not revoke signed URLs already issued.",
      "type": "boolean"
    },
    "preview_url": {
      "description": "Public HLS preview URL. Available when playback_ready and preview_enabled are true. No API token is required.",
      "format": "uri",
      "type": "string"
    },
    "ready_at": {
      "description": "When all required Asset outputs finished processing.",
      "format": "date-time",
      "type": "string"
    },
    "size": {
      "description": "Size specifies the total bytes of available streaming, playback preview, poster, and timeline files. Excludes static renditions. Omitted until the Asset is ready.",
      "minimum": 0,
      "type": "integer"
    },
    "source_id": {
      "description": "Original Source ID. Omitted after Source deletion.",
      "type": "string"
    },
    "source_metadata": {
      "$ref": "#/components/schemas/AssetSourceMetadata"
    },
    "status": {
      "$ref": "#/components/schemas/AssetStatus",
      "description": "Status specifies the Asset preparation state. ready means the video is prepared for playback, with its poster and timeline previews available. Static renditions and captions have independent statuses."
    },
    "storage_id": {
      "description": "ID of the output Storage.",
      "type": "string"
    },
    "timeline_previews": {
      "$ref": "#/components/schemas/AssetTimelinePreviews",
      "description": "Timeline thumbnails. The WebVTT file maps video timestamps to image URLs and crop coordinates."
    },
    "title": {
      "description": "Asset title.",
      "type": "string"
    },
    "updated_at": {
      "description": "When the Asset was last updated.",
      "format": "date-time",
      "type": "string"
    },
    "workflow_id": {
      "description": "Selected Workflow ID, or null.",
      "type": [
        "string",
        "null"
      ]
    },
    "workflow_revision": {
      "description": "Pinned Workflow revision, or null.",
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "required": [
    "playback_ready",
    "id",
    "source_metadata",
    "title",
    "status",
    "metadata",
    "storage_id",
    "preview_enabled",
    "created_at",
    "updated_at",
    "can_add_static_renditions",
    "min_resolution",
    "max_resolution",
    "workflow_id",
    "workflow_revision"
  ],
  "type": "object"
}
```



```json #/components/schemas/CreatedVia
{
  "description": "CreatedVia specifies how the resource was created: api for API requests, dashboard for the Chunkify dashboard, mcp for MCP clients, and workflow for Workflow actions.\nOmitted when the creator is unknown.",
  "enum": [
    "api",
    "dashboard",
    "mcp",
    "workflow"
  ],
  "examples": [
    "api"
  ],
  "type": "string"
}
```



```json #/components/schemas/AssetError
{
  "properties": {
    "code": {
      "description": "Machine-readable processing error code.",
      "type": "string"
    },
    "message": {
      "description": "Description of the processing failure.",
      "type": "string"
    },
    "stage": {
      "description": "Processing stage that failed.",
      "enum": [
        "ingest",
        "analysis",
        "encoding",
        "packaging",
        "upload",
        "validation",
        "cleanup"
      ],
      "type": "string"
    }
  },
  "required": [
    "stage",
    "code",
    "message"
  ],
  "type": "object"
}
```



```json #/components/schemas/AssetPoster
{
  "properties": {
    "cdn_url": {
      "description": "Unsigned image CDN URL. Available once the poster exists and Storage has a CDN URL.",
      "format": "uri",
      "type": "string"
    },
    "height": {
      "description": "Image height in pixels.",
      "minimum": 0,
      "type": "integer"
    },
    "path": {
      "description": "Image path in Storage.",
      "type": "string"
    },
    "preview_url": {
      "description": "Public poster preview URL. Available when the Asset is ready and preview_enabled is true.",
      "format": "uri",
      "type": "string"
    },
    "size": {
      "description": "Image size in bytes.",
      "minimum": 0,
      "type": "integer"
    },
    "time_seconds": {
      "description": "Position of the selected frame in seconds.",
      "minimum": 0,
      "type": "number"
    },
    "url": {
      "description": "Signed image URL, valid for up to ten minutes. Available once the poster exists, regardless of preview_enabled.",
      "format": "uri",
      "type": "string"
    },
    "width": {
      "description": "Image width in pixels.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "path",
    "width",
    "height"
  ],
  "type": "object"
}
```



```json #/components/schemas/AssetSourceMetadata
{
  "description": "Original media metadata saved at Asset creation and preserved after Source deletion.",
  "properties": {
    "audio_bitrate": {
      "description": "Original audio bitrate in bits per second, or zero when unavailable.",
      "type": "integer"
    },
    "audio_codec": {
      "description": "Original audio codec, or an empty string when there is no audio.",
      "type": "string"
    },
    "audio_samplerate": {
      "description": "Original audio sample rate in Hz, or zero when unavailable.",
      "type": "integer"
    },
    "duration": {
      "description": "Original duration in seconds.",
      "type": "number"
    },
    "height": {
      "description": "Original video height in pixels.",
      "type": "integer"
    },
    "size": {
      "description": "Original file size in bytes.",
      "type": "integer"
    },
    "video_bitrate": {
      "description": "Original video bitrate in bits per second, or zero when unknown.",
      "type": "integer"
    },
    "video_codec": {
      "description": "Original video codec.",
      "type": "string"
    },
    "video_framerate": {
      "description": "Original video frame rate in frames per second.",
      "type": "number"
    },
    "width": {
      "description": "Original video width in pixels.",
      "type": "integer"
    }
  },
  "required": [
    "width",
    "height",
    "duration",
    "size",
    "video_framerate",
    "video_codec",
    "video_bitrate",
    "audio_codec",
    "audio_bitrate",
    "audio_samplerate"
  ],
  "type": "object"
}
```



```json #/components/schemas/AssetStatus
{
  "enum": [
    "preparing",
    "ready",
    "failed",
    "expired"
  ],
  "type": "string"
}
```



```json #/components/schemas/AssetTimelinePreviews
{
  "properties": {
    "cdn_url": {
      "description": "Unsigned WebVTT CDN URL. Available when the Asset is ready and Storage has a CDN URL.",
      "format": "uri",
      "type": "string"
    },
    "format": {
      "const": "sprite",
      "description": "Thumbnail image layout.",
      "type": "string"
    },
    "image_count": {
      "description": "Number of thumbnails.",
      "minimum": 0,
      "type": "integer"
    },
    "interval_seconds": {
      "description": "Target thumbnail sampling interval in seconds. The WebVTT file provides actual cue timestamps.",
      "minimum": 0,
      "type": "number"
    },
    "preview_url": {
      "description": "Public WebVTT preview URL with signed image references. Available when the Asset is ready and preview_enabled is true.",
      "format": "uri",
      "type": "string"
    },
    "size": {
      "description": "Combined WebVTT and sprite image size in bytes.",
      "minimum": 0,
      "type": "integer"
    },
    "sprite_count": {
      "description": "Number of sprite images containing the thumbnails.",
      "minimum": 0,
      "type": "integer"
    },
    "thumbnail_height": {
      "description": "Thumbnail height in pixels.",
      "minimum": 0,
      "type": "integer"
    },
    "thumbnail_width": {
      "description": "Thumbnail width in pixels.",
      "minimum": 0,
      "type": "integer"
    },
    "vtt_path": {
      "description": "WebVTT file path in Storage.",
      "type": "string"
    }
  },
  "required": [
    "format",
    "vtt_path"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorValidation
{
  "properties": {
    "error": {
      "properties": {
        "code": {
          "const": 400,
          "description": "Code is the HTTP status code",
          "examples": [
            400
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Invalid request parameters"
          ],
          "type": "string"
        },
        "type": {
          "const": "ValidationError",
          "description": "Type indicates the error category",
          "enum": [
            "ValidationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```



```json #/components/schemas/ResponseErrorAuthentication
{
  "description": "Error response",
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 401,
          "description": "Code is the HTTP status code",
          "examples": [
            401
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Authentication error: invalid token or subscription inactive"
          ],
          "type": "string"
        },
        "type": {
          "const": "AuthenticationError",
          "description": "Type indicates the error category",
          "enum": [
            "AuthenticationError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ],
  "type": "object"
}
```



```json #/components/schemas/ResponseErrorForbidden
{
  "properties": {
    "error": {
      "description": "Error response details",
      "properties": {
        "code": {
          "const": 403,
          "description": "Code is the HTTP status code",
          "examples": [
            403
          ],
          "type": "integer"
        },
        "message": {
          "description": "Message is a human-readable error description",
          "examples": [
            "Unauthorized to perform this action"
          ],
          "type": "string"
        },
        "type": {
          "const": "ForbiddenError",
          "description": "Type indicates the error category",
          "enum": [
            "ForbiddenError"
          ],
          "type": "string"
        }
      },
      "required": [
        "type",
        "code",
        "message"
      ],
      "type": "object"
    },
    "status": {
      "const": "error",
      "description": "Status indicates the response status \"error\"",
      "type": "string"
    }
  },
  "required": [
    "status",
    "error"
  ]
}
```