Skip to main content
GET
/
v1
/
user-media
curl -X GET "https://api.submagic.co/v1/user-media?type=AUDIO&limit=10" \
  -H "x-api-key: sk-your-api-key-here"

{
  "items": [
    {
      "id": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "type": "AUDIO",
      "fileName": "background-music.mp3",
      "url": "https://cdn.submagic.co/media/88a08eec-712a-45d0-8d0b-3b631700cb3a.mp3",
      "metadata": {
        "duration": 180.5,
        "fileSize": 4500000
      },
      "createdAt": "2024-01-10T08:00:00.000Z"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "VIDEO",
      "fileName": "broll-clip.mp4",
      "url": "https://cdn.submagic.co/media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp4",
      "metadata": {
        "width": 1920,
        "height": 1080,
        "duration": 12.3,
        "fileSize": 15000000
      },
      "createdAt": "2024-01-09T14:30:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "f5e4d3c2-b1a0-9876-fedc-ba0987654321"
}

​
List User Media

Retrieve a paginated list of media files from your library. You can filter by media type and control pagination using cursor-based navigation.
This endpoint requires authentication and has a rate limit of 500 requests per hour.

​
Authentication

​
x-api-key
string
required
Your Submagic API key starting with sk-

​
Query Parameters

​
type
string
Filter by media type. Allowed values: VIDEO, AUDIO, IMAGE.
​
limit
number
Number of items to return per page (1-100). Defaults to 50.
​
cursor
string
UUID cursor for pagination. Pass the nextCursor value from a previous response to fetch the next page of results.

​
Response

​
items
array
Array of user media objects
​
hasMore
boolean
Whether there are more items available beyond this page
​
nextCursor
string
Cursor to pass as the cursor query parameter to fetch the next page. Only present when hasMore is true.
curl -X GET "https://api.submagic.co/v1/user-media?type=AUDIO&limit=10" \
  -H "x-api-key: sk-your-api-key-here"

{
  "items": [
    {
      "id": "88a08eec-712a-45d0-8d0b-3b631700cb3a",
      "type": "AUDIO",
      "fileName": "background-music.mp3",
      "url": "https://cdn.submagic.co/media/88a08eec-712a-45d0-8d0b-3b631700cb3a.mp3",
      "metadata": {
        "duration": 180.5,
        "fileSize": 4500000
      },
      "createdAt": "2024-01-10T08:00:00.000Z"
    },
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "type": "VIDEO",
      "fileName": "broll-clip.mp4",
      "url": "https://cdn.submagic.co/media/a1b2c3d4-e5f6-7890-abcd-ef1234567890.mp4",
      "metadata": {
        "width": 1920,
        "height": 1080,
        "duration": 12.3,
        "fileSize": 15000000
      },
      "createdAt": "2024-01-09T14:30:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "f5e4d3c2-b1a0-9876-fedc-ba0987654321"
}

​
Error Responses

​
400 Validation Error
object
{
  "error": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "type",
      "message": "Must be one of: VIDEO, AUDIO, IMAGE",
      "value": "INVALID"
    }
  ]
}
​
401 Unauthorized
object
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
​
429 Rate Limited
object
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 30
}
​
500 Server Error
object
{
  "error": "INTERNAL_SERVER_ERROR",
  "message": "An unexpected error occurred"
}