> ## 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.

# Get File Metadata

> Retrieve metadata for a specific file

## Overview

This endpoint returns the full metadata record for a specific file in the authenticated organization, including file status, size, and type-specific attributes (image dimensions, tabular shape, etc.).

## Path Parameters

<ParamField path="file_id" type="string" required>
  Identifier of the file whose metadata to fetch
</ParamField>

## Response

<ResponseField name="file_id" type="string">
  Identifier of the file
</ResponseField>

<ResponseField name="file_uid" type="string">
  Internal unique identifier of the file
</ResponseField>

<ResponseField name="is_valid" type="boolean">
  Whether the metadata record is valid
</ResponseField>

<ResponseField name="file_type" type="string">
  MIME type of the file (e.g. `image/png`, `text/csv`)
</ResponseField>

<ResponseField name="num_bytes" type="integer">
  Size of the file in bytes
</ResponseField>

<ResponseField name="file_status" type="string">
  Lifecycle status of the file. One of:

  * `FILE_STATUS_UNKNOWN`
  * `FILE_STATUS_REGISTERED`
  * `FILE_STATUS_INGESTING`
  * `FILE_STATUS_INGESTED`
  * `FILE_STATUS_IN_MEMORY`
  * `FILE_STATUS_IN_COLD_STORAGE`
  * `FILE_STATUS_CORRUPT`
</ResponseField>

<ResponseField name="ingested" type="boolean">
  Whether the file has completed ingestion
</ResponseField>

<ResponseField name="file_index" type="integer">
  Index of this file within the organization's file list
</ResponseField>

<ResponseField name="file_tags" type="object">
  Key/value tags attached to the file (empty object if no tags)
</ResponseField>

<ResponseField name="file_attributes" type="object">
  Type-specific attributes for the file. The shape varies by file type:

  <Expandable title="image attributes">
    <ResponseField name="width" type="integer">
      Image width in pixels
    </ResponseField>

    <ResponseField name="height" type="integer">
      Image height in pixels
    </ResponseField>

    <ResponseField name="num_channels" type="integer">
      Number of color channels
    </ResponseField>

    <ResponseField name="channel_bands" type="array">
      Channel band labels (e.g. `["R", "G", "B"]`)
    </ResponseField>
  </Expandable>

  <Expandable title="tabular attributes">
    <ResponseField name="num_columns" type="integer">
      Number of columns
    </ResponseField>

    <ResponseField name="column_headers" type="array">
      Column header names
    </ResponseField>

    <ResponseField name="num_rows" type="integer">
      Number of rows. Only present when the platform was able to extract row counts at upload time — large files and direct-to-cloud uploads typically omit this field.
    </ResponseField>
  </Expandable>

  <Expandable title="metadata not extracted">
    <ResponseField name="metadata_status" type="string">
      `not_extracted` — file was too large for inline metadata extraction. Contact platform maintainers if you need metadata for this file.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

  api_key = os.environ.get("ATAI_API_KEY")
  file_id = "file-abc123"

  response = requests.get(
      "https://api.u1.archetypeai.app/v0.5/files/metadata/test_image.jpg",
      headers={"Authorization": f"Bearer {api_key}"}
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"system"}
  const fileId = "file-abc123";

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

  const metadata = await response.json();
  console.log(metadata);
  ```
</RequestExample>

<ResponseExample>
  ```json 200 - Success (image) 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": {}
  }
  ```

  ```json 200 - Success (tabular) theme={"system"}
  {
    "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 200 - Success (metadata not extracted) theme={"system"}
  {
    "file_id": "file-large-789",
    "file_uid": "9a0b1c2d-3e4f-5061-7283-94a5b6c7d8e9",
    "is_valid": true,
    "file_type": "video/mp4",
    "num_bytes": 4831785472,
    "file_status": "FILE_STATUS_INGESTED",
    "file_attributes": {
      "metadata_status": "not_extracted"
    },
    "ingested": true,
    "file_index": 2,
    "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"
      }
    ]
  }
  ```

  ```json 404 - File not found theme={"system"}
  {
    "errors": [
      {
        "code": "file_not_found",
        "message": "No file with the given file_id was found for the organization.",
        "suggestion": "Verify the file_id and that the file has not been deleted.",
        "error_uid": "err-xxxxxxxx"
      }
    ]
  }
  ```
</ResponseExample>