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

# List Files Metadata

> List metadata for all files in the authenticated organization

## Overview

This endpoint returns a list of metadata records for files belonging to your organization. Use
the optional sharding parameters to page through large file collections.

The list is partitioned into shards of `max_items_per_shard` items, and `shard_index` selects
which shard to return. Both parameters are optional — when omitted, the server returns the full
set, up to 1000 maximum records.

## Query Parameters

<ParamField query="shard_index" type="integer" default="-1">
  Zero-based index of the shard to return. Use together with `max_items_per_shard` to page through results. Specify `-1` to retrieve all files.
</ParamField>

<ParamField query="max_items_per_shard" type="integer" default="-1">
  Maximum number of metadata records per shard. Specify `-1` for the maximum allowed number of records per shard. The maximum number of records per shard is 1000.
</ParamField>

<ParamField query="file_type" type="string">
  Filter results to a single exact MIME type (e.g. `image/png`, `text/csv`). Omit to return
  files of all types. <Badge color="blue">[v1.1.2+](/release-notes/1.1.x#v1-1-2)</Badge>
</ParamField>

## Response

Returns an array of file metadata records. Each record has the same shape as the response from
[Get File Metadata](./get-metadata).

<RequestExample>
  ```bash cURL - All Files theme={"system"}
  curl https://api.u1.archetypeai.app/v0.5/files/metadata \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```bash cURL - With Pagination theme={"system"}
  curl "https://api.u1.archetypeai.app/v0.5/files/metadata?shard_index=0&max_items_per_shard=10" \
    -H "Authorization: Bearer $ATAI_API_KEY"
  ```

  ```python Python theme={"system"}
  import requests
  import os

  api_key = os.environ.get("ATAI_API_KEY")

  response = requests.get(
      "https://api.u1.archetypeai.app/v0.5/files/metadata",
      headers={"Authorization": f"Bearer {api_key}"},
      params={"shard_index": 0, "max_items_per_shard": 100},
  )

  for file in response.json():
      print(f"{file['file_id']}  {file['file_status']}  {file['num_bytes']} bytes")
  ```

  ```javascript JavaScript theme={"system"}
  const params = new URLSearchParams({
    shard_index: "0",
    max_items_per_shard: "100",
  });

  const response = await fetch(
    `https://api.u1.archetypeai.app/v0.5/files/metadata?${params}`,
    {
      headers: {
        Authorization: `Bearer ${process.env.ATAI_API_KEY}`,
      },
    }
  );

  const files = await response.json();
  for (const f of files) {
    console.log(`${f.file_id}  ${f.file_status}  ${f.num_bytes} bytes`);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success theme={"system"}
  [
    {
      "file_id": "file-abc123",
      "file_uid": "8f2c1e5a-7b3d-4d9e-9c1a-2f5b7d8e4a6c",
      "is_valid": true,
      "file_type": "image/png",
      "num_bytes": 482931,
      "file_status": "FILE_STATUS_INGESTED",
      "file_attributes": {
        "width": 1920,
        "height": 1080,
        "num_channels": 3,
        "channel_bands": ["R", "G", "B"]
      },
      "ingested": true,
      "file_index": 0,
      "file_tags": {}
    },
    {
      "file_id": "file-def456",
      "file_uid": "1d4f9b2e-3a8c-4e1d-bb02-7d6c9f0a3b51",
      "is_valid": true,
      "file_type": "text/csv",
      "num_bytes": 12483910,
      "file_status": "FILE_STATUS_INGESTED",
      "file_attributes": {
        "num_rows": 50000,
        "num_columns": 24,
        "column_headers": ["timestamp", "value", "label"]
      },
      "ingested": true,
      "file_index": 1,
      "file_tags": {}
    }
  ]
  ```

  ```json 401 - Unauthorized theme={"system"}
  {
    "errors": [
      {
        "code": "unauthorized_request",
        "message": "Unauthorized or invalid access.",
        "suggestion": "Provide valid authentication credentials and ensure they have the required permissions.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>