Listing Your Media

Retrieve a paginated list of media items from a specific dataset.

Endpoint

GET /api/dataset/{datasetId}/media

Path Parameters

Parameter	Type	Description
`datasetId`	string	The unique identifier of the dataset

Query Parameters

Parameter	Type	Required	Default	Description
`limit`	integer	No	10	Maximum number of media items to return
`offset`	integer	No	0	Number of items to skip for pagination
`sortDirection`	string	No	`asc`	Sort order: `asc` or `desc`

Headers

Header	Value	Required
`x-api-key`	Your API key	Yes

Example Request

curl -H "x-api-key: YOUR_API_KEY" \
  "https://lab.coreviz.io/api/dataset/ecf33096-0d69-410b-a8cc-856caa3fba6c/media?limit=9&offset=0&sortDirection=desc"

Response

Status Code: 200 OK

Response Body:

{
  "media": [
    {
      "id": "7938b58d-d60a-43d8-953f-4f56b3cd8410",
      "name": "entities/d5979219-6891-4514-8096-0aa7d8898d33/media/convert.webp",
      "type": "image",
      "blob": "https://3vxmbaxifmu58irw.public.blob.vercel-storage.com/entities/d5979219-6891-4514-8096-0aa7d8898d33/media/convert-WjWBdnEdxK4ZtfEnZa8gV9cdy7N7aU.webp",
      "entityId": "d5979219-6891-4514-8096-0aa7d8898d33",
      "width": 2000,
      "height": 1161,
      "duration": null,
      "sizeBytes": 100120,
      "exif": {
        "tags": {}
      },
      "createdAt": "2025-11-22T01:27:59.555Z",
      "updatedAt": "2025-11-22T01:27:59.555Z",
      "metadata": {
        "tags": {
          "Tags": ["24"]
        },
        "moderation": {
          "status": "approved",
          "categories": [],
          "moderatedAt": "2025-11-22T01:27:59.520Z"
        }
      },
      "createdById": "3752284a-3d51-400b-957c-cb8e03d937f2",
      "updatedById": null,
      "status": "active",
      "frames": [
        {
          "id": "c56a0b9d-0d8f-49fc-9c01-1d0387ca5f7b",
          "timestamp": "0",
          "blob": "https://3vxmbaxifmu58irw.public.blob.vercel-storage.com/entities/d5979219-6891-4514-8096-0aa7d8898d33/media/7938b58d-d60a-43d8-953f-4f56b3cd8410/processed-zOXhoEHIJAfIyZEq6yeLHekBn2a6yL.jpg",
          "width": 1860,
          "height": 1080,
          "createdAt": "2025-11-22T01:28:07.863Z",
          "updatedAt": "2025-11-22T01:28:07.863Z",
          "status": "active",
          "createdById": "3752284a-3d51-400b-957c-cb8e03d937f2",
          "metadata": {
            "moderation": {
              "status": "approved",
              "categories": [],
              "moderatedAt": "2025-11-22T01:27:59.520Z"
            }
          },
          "mediaId": "7938b58d-d60a-43d8-953f-4f56b3cd8410",
          "captions": [
            {
              "id": "19a28556-b279-4a79-85d8-2762546f9320",
              "text": "A dark-skinned man with dark curly hair wears a green football jersey with the number 24 in white and gold lettering. He holds a brown football with a white stripe in his right hand and points with his left hand. He wears green gloves. The background is a large green and tan banner with a stylized \"Tampa\" logo.",
              "frameId": "c56a0b9d-0d8f-49fc-9c01-1d0387ca5f7b",
              "createdAt": "2025-11-22T01:28:19.597Z",
              "updatedAt": "2025-11-22T01:28:19.597Z",
              "status": "active",
              "createdById": "3752284a-3d51-400b-957c-cb8e03d937f2",
              "metadata": {},
            }
          ],
          "objects": []
        }
      ]
    }
  ],
  "pagination": {
    "total": 6,
    "limit": 9,
    "offset": 0,
    "hasMore": false
  }
}

Response Fields

Media Object

Field	Type	Description
`id`	string	Unique identifier for the media item
`name`	string	File path/name of the media
`type`	string	Media type: `image` or `video`
`blob`	string	URL to the media file
`entityId`	string	ID of the entity this media belongs to
`width`	integer	Width in pixels (for images/videos)
`height`	integer	Height in pixels (for images/videos)
`duration`	number \| null	Duration in seconds (for videos, null for images)
`sizeBytes`	integer	File size in bytes
`exif`	object	EXIF metadata from the file
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update
`metadata`	object	Additional metadata including tags and moderation status
`createdById`	string	ID of the user who created this media
`updatedById`	string \| null	ID of the user who last updated this media
`status`	string	Status of the media item (e.g., `active`)
`frames`	array	Array of frame objects (for videos or processed images)

Frame Object

Field	Type	Description
`id`	string	Unique identifier for the frame
`timestamp`	string	Timestamp within the video (or "0" for images)
`blob`	string	URL to the processed frame image
`width`	integer	Frame width in pixels
`height`	integer	Frame height in pixels
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update
`status`	string	Status of the frame
`createdById`	string	ID of the user who created this frame
`metadata`	object	Frame-specific metadata
`mediaId`	string	ID of the parent media item
`captions`	array	Array of caption objects generated by AI
`objects`	array	Array of detected objects in the frame

Caption Object

Field	Type	Description
`id`	string	Unique identifier for the caption
`text`	string	The caption text
`frameId`	string	ID of the frame this caption describes
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update
`status`	string	Status of the caption
`createdById`	string	ID of the user who created this caption
`metadata`	object	Additional caption metadata
`model`	string	AI model used to generate the caption

Pagination Object

Field	Type	Description
`total`	integer	Total number of media items in the dataset
`limit`	integer	Maximum number of items requested
`offset`	integer	Number of items skipped
`hasMore`	boolean	Whether there are more items available

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

404 Not Found

Dataset not found:

{
  "error": "Not Found",
  "message": "Dataset not found"
}

400 Bad Request

Invalid query parameters:

{
  "error": "Bad Request",
  "message": "Invalid query parameters"
}

Example Usage

JavaScript/TypeScript

const datasetId = 'ecf33096-0d69-410b-a8cc-856caa3fba6c';
const apiKey = 'YOUR_API_KEY';

const response = await fetch(
  `https://lab.coreviz.io/api/dataset/${datasetId}/media?limit=9&offset=0&sortDirection=desc`,
  {
    headers: {
      'x-api-key': apiKey,
    },
  }
);

const data = await response.json();
console.log(data.media);
console.log(data.pagination);

Python

import requests

dataset_id = 'ecf33096-0d69-410b-a8cc-856caa3fba6c'
api_key = 'YOUR_API_KEY'

response = requests.get(
    f'https://lab.coreviz.io/api/dataset/{dataset_id}/media',
    headers={'x-api-key': api_key},
    params={
        'limit': 9,
        'offset': 0,
        'sortDirection': 'desc'
    }
)

data = response.json()
print(data['media'])
print(data['pagination'])

Pagination

Use the limit and offset parameters to paginate through results:

First page: limit=9&offset=0
Second page: limit=9&offset=9
Third page: limit=9&offset=18

Check the hasMore field in the pagination object to determine if more results are available.

Notes

Media items are returned with their associated frames, captions, and detected objects
The blob URLs are publicly accessible and can be used directly in your applications
Frames are generated for videos and processed images, containing extracted or processed versions
Captions are generated by AI models and provide descriptive text about the content
The metadata object contains tags and moderation information that can be used for filtering and organization

Listing Your Media

On this page