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

# List Assets

> Retrieve a paginated list of all your uploaded assets

## Overview

Get a list of all assets you've uploaded to Babou. Supports pagination and filtering by content type and state.

## Request

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer sk-bab-your-api-key`
</ParamField>

### Query Parameters

<ParamField query="limit" type="number" default="20">
  Number of assets to return per page (max: 100)
</ParamField>

<ParamField query="offset" type="number" default="0">
  Number of assets to skip for pagination
</ParamField>

<ParamField query="contentType" type="string">
  Filter by MIME type (e.g., `image/png`, `video/mp4`)
</ParamField>

<ParamField query="state" type="string">
  Filter by state: `uploading`, `ready`, or `failed`
</ParamField>

## Response

<ResponseField name="assets" type="array">
  Array of asset objects

  <Expandable title="Asset object">
    <ResponseField name="id" type="string">
      Unique identifier for the asset
    </ResponseField>

    <ResponseField name="url" type="string">
      Public URL to access the asset
    </ResponseField>

    <ResponseField name="content_type" type="string">
      MIME type of the file
    </ResponseField>

    <ResponseField name="size" type="number">
      File size in bytes
    </ResponseField>

    <ResponseField name="state" type="string">
      Current state: `uploading`, `ready`, or `failed`
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata

  <Expandable title="Pagination object">
    <ResponseField name="limit" type="number">
      Items per page
    </ResponseField>

    <ResponseField name="offset" type="number">
      Items skipped
    </ResponseField>

    <ResponseField name="total" type="number">
      Total number of assets matching the filters
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  # List all assets
  curl https://api.babou.ai/api/v1/assets \
    -H "Authorization: Bearer $BABOU_API_KEY"

  # List with pagination
  curl "https://api.babou.ai/api/v1/assets?limit=50&offset=100" \
    -H "Authorization: Bearer $BABOU_API_KEY"

  # Filter by content type
  curl "https://api.babou.ai/api/v1/assets?contentType=video/mp4" \
    -H "Authorization: Bearer $BABOU_API_KEY"

  # Filter by state
  curl "https://api.babou.ai/api/v1/assets?state=ready" \
    -H "Authorization: Bearer $BABOU_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  interface ListAssetsOptions {
    limit?: number;
    offset?: number;
    contentType?: string;
    state?: 'uploading' | 'ready' | 'failed';
  }

  async function listAssets(options: ListAssetsOptions = {}) {
    const params = new URLSearchParams();

    if (options.limit) params.append('limit', options.limit.toString());
    if (options.offset) params.append('offset', options.offset.toString());
    if (options.contentType) params.append('contentType', options.contentType);
    if (options.state) params.append('state', options.state);

    const response = await fetch(
      `https://api.babou.ai/api/v1/assets?${params}`,
      {
        headers: {
          'Authorization': `Bearer ${process.env.BABOU_API_KEY}`
        }
      }
    );

    return await response.json();
  }

  // List all assets
  const allAssets = await listAssets();

  // List only videos
  const videos = await listAssets({ contentType: 'video/mp4' });

  // Paginate through assets
  const page2 = await listAssets({ limit: 20, offset: 20 });

  console.log(`Found ${allAssets.pagination.total} total assets`);
  console.log(`First asset: ${allAssets.assets[0]?.url}`);
  ```

  ```python Python theme={null}
  import os
  import requests
  from typing import Optional

  def list_assets(
      limit: Optional[int] = None,
      offset: Optional[int] = None,
      content_type: Optional[str] = None,
      state: Optional[str] = None
  ):
      params = {}
      if limit: params['limit'] = limit
      if offset: params['offset'] = offset
      if content_type: params['contentType'] = content_type
      if state: params['state'] = state

      response = requests.get(
          'https://api.babou.ai/api/v1/assets',
          headers={'Authorization': f'Bearer {os.environ["BABOU_API_KEY"]}'},
          params=params
      )

      return response.json()

  # List all assets
  all_assets = list_assets()

  # List only videos
  videos = list_assets(content_type='video/mp4')

  # Paginate through assets
  page_2 = list_assets(limit=20, offset=20)

  print(f'Found {all_assets["pagination"]["total"]} total assets')
  print(f'First asset: {all_assets["assets"][0]["url"] if all_assets["assets"] else "None"}')
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "assets": [
    {
      "id": "ast_abc123xyz456789012",
      "name": "logo.png",
      "url": "s3://babou-assets/assets/ast_abc123xyz456789012-original",
      "content_type": "image/png",
      "size": 245678,
      "state": "ready",
      "duration": null,
      "width": 1920,
      "height": 1080,
      "created_at": "2025-12-02T10:00:00Z"
    },
    {
      "id": "ast_def456uvw987654321",
      "name": "intro.mp4",
      "url": "s3://babou-assets/assets/ast_def456uvw987654321-original",
      "content_type": "video/mp4",
      "size": 15234567,
      "state": "ready",
      "duration": 45.2,
      "width": 1920,
      "height": 1080,
      "created_at": "2025-12-02T09:30:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 42
  }
}
```

## Pagination

To iterate through all assets, use the `offset` parameter:

<CodeGroup>
  ```typescript TypeScript theme={null}
  async function getAllAssets() {
    const allAssets = [];
    let offset = 0;
    const limit = 100; // Max per page

    while (true) {
      const response = await listAssets({ limit, offset });
      allAssets.push(...response.assets);

      if (allAssets.length >= response.pagination.total) {
        break;
      }

      offset += limit;
    }

    return allAssets;
  }

  const assets = await getAllAssets();
  console.log(`Retrieved all ${assets.length} assets`);
  ```

  ```python Python theme={null}
  def get_all_assets():
      all_assets = []
      offset = 0
      limit = 100  # Max per page

      while True:
          response = list_assets(limit=limit, offset=offset)
          all_assets.extend(response['assets'])

          if len(all_assets) >= response['pagination']['total']:
              break

          offset += limit

      return all_assets

  assets = get_all_assets()
  print(f'Retrieved all {len(assets)} assets')
  ```
</CodeGroup>

## Filtering Examples

<AccordionGroup>
  <Accordion title="Get all images">
    ```typescript theme={null}
    const images = await listAssets({ contentType: 'image/png' });
    // Or filter for any image type in your application
    const allImages = (await listAssets()).assets.filter(
      asset => asset.content_type.startsWith('image/')
    );
    ```
  </Accordion>

  <Accordion title="Get all videos">
    ```python theme={null}
    videos = list_assets(content_type='video/mp4')

    # Or filter for any video type
    all_assets = list_assets()
    all_videos = [
        asset for asset in all_assets['assets']
        if asset['content_type'].startswith('video/')
    ]
    ```
  </Accordion>

  <Accordion title="Check for failed uploads">
    ```typescript theme={null}
    const failedUploads = await listAssets({ state: 'failed' });

    if (failedUploads.assets.length > 0) {
      console.warn(`Found ${failedUploads.assets.length} failed uploads`);
      // Retry or clean up failed uploads
    }
    ```
  </Accordion>

  <Accordion title="Find recent uploads">
    ```python theme={null}
    from datetime import datetime, timedelta

    assets = list_assets(limit=100)
    one_hour_ago = datetime.now() - timedelta(hours=1)

    recent = [
        asset for asset in assets['assets']
        if datetime.fromisoformat(asset['created_at'].replace('Z', '+00:00')) > one_hour_ago
    ]

    print(f'Found {len(recent)} assets uploaded in the last hour')
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Upload Asset" icon="upload" href="/api-reference/assets/upload">
    Upload a new asset
  </Card>

  <Card title="Get Asset" icon="download" href="/api-reference/assets/get">
    Retrieve specific asset details
  </Card>

  <Card title="Asset Management Guide" icon="folder" href="/guides/asset-management">
    Learn how to use assets in your videos
  </Card>
</CardGroup>