> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/api/file-download.md).

# File Download

## Retrieve File List Information for Reports

#### Endpoint

```
POST /v1/company_report/file_list
```

[**Try it out in API Playground →**](https://api.orbitfin.ai/docs#/reports/get_file_list_v1_company_report_file_list_post)

#### Description

Obtain different types of file information based on a list of report IDs and query options. The API supports three distinct query modes: `pdf` for document metadata retrieval, `extract` for text extraction results, and `embedding` for vector embedding data. This endpoint enables batch retrieval of file metadata and content across multiple reports simultaneously.

***

### Request

#### Headers

| Name           | Type   | Required | Description        |
| -------------- | ------ | -------- | ------------------ |
| `Content-Type` | string | Yes      | `application/json` |
| `X-API-KEY`    | string | Yes      | Your API key       |

#### Request Body Parameters

| Parameter   | Type           | Required | Description                                                                      |
| ----------- | -------------- | -------- | -------------------------------------------------------------------------------- |
| `report_id` | array\[string] | Yes      | List of report IDs to retrieve file information for                              |
| `option`    | array\[string] | Yes      | Query mode options: `pdf`, `extract`, or `embedding` (supports multiple options) |

**Query Mode Options**

| Option      | Description                                        |
| ----------- | -------------------------------------------------- |
| `pdf`       | Retrieves PDF document metadata and download links |
| `extract`   | Obtains text extraction results                    |
| `embedding` | Accesses vector embedding data                     |

#### Example Request

```bash
curl -X 'POST' \
  'https://api.orbitfin.ai/v1/company_report/file_list' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "report_id": [
    "f_haBmMwT4WN7tXrt8rj9eA3"
  ],
  "option": [
    "pdf"
  ]
}'
```

***

### Response

#### Response Fields

**Top-Level Fields**

| Field         | Type    | Description                             |
| ------------- | ------- | --------------------------------------- |
| `status_code` | integer | HTTP status code (200 for success)      |
| `data`        | object  | Container object holding file list data |
| `message`     | string  | Response status message                 |

**Data Object**

| Field                 | Type   | Description                             |
| --------------------- | ------ | --------------------------------------- |
| `file_list_pdf`       | array  | Array of PDF file metadata objects      |
| `file_list_extract`   | array  | Array of text extraction result objects |
| `file_list_embedding` | array  | Array of vector embedding data objects  |
| `billing_info`        | object | Billing information for the API call    |

**PDF File Object (`data.file_list_pdf[]`)**

| Field            | Type    | Description                                            |
| ---------------- | ------- | ------------------------------------------------------ |
| `report_id`      | string  | Unique identifier for the report                       |
| `file_title`     | string  | Original title of the file                             |
| `file_title_en`  | string  | English translation of the file title                  |
| `clickable_link` | string  | Pre-signed download URL (valid for 7 days)             |
| `page_count`     | integer | Total number of pages in the PDF document              |
| `language`       | string  | Language code of the document (e.g., `en` for English) |

**Billing Info Object (`data.billing_info`)**

| Field           | Type    | Description                                    |
| --------------- | ------- | ---------------------------------------------- |
| `total_calls`   | integer | Total number of API calls made in this request |
| `total_options` | integer | Total number of query options processed        |
| `total_charge`  | integer | Total credits charged for this request         |

#### Example Response

```json
{
  "status_code": 200,
  "data": {
    "file_list_pdf": [
      {
        "report_id": "f_haBmMwT4WN7tXrt8rj9eA3",
        "file_title": "Quarterly Report",
        "file_title_en": "Quarterly Report",
        "clickable_link": "https://filing-reports.s3.amazonaws.com/reports-data/stock_us/2025/08/08/edgar-data-1756701-000095017025105920-lnkb-20250630.htm.pdf?AWSAccessKeyId=AKIAZ2SDT5DUYIU3G434&Signature=XMVRHLuKS9Y45BPKjK7dhmlVcHA%3D&Expires=1761229440",
        "page_count": 60,
        "language": "en"
      },
      {
        "report_id": "f_haBmMwT4WN7tXrt8rj9eA3",
        "file_title": "Quarterly Report",
        "file_title_en": "Quarterly Report",
        "clickable_link": "https://filing-reports.s3.amazonaws.com/reports-data/stock_us/2025/08/08/edgar-data-1756701-000095017025105920-lnkb-ex31_2.htm.pdf?AWSAccessKeyId=AKIAZ2SDT5DUYIU3G434&Signature=N07B28t4dQmMbR9Fs6gM%2Bl%2BBBPM%3D&Expires=1761229440",
        "page_count": 1,
        "language": "en"
      },
      {
        "report_id": "f_haBmMwT4WN7tXrt8rj9eA3",
        "file_title": "Quarterly Report",
        "file_title_en": "Quarterly Report",
        "clickable_link": "https://filing-reports.s3.amazonaws.com/reports-data/stock_us/2025/08/08/edgar-data-1756701-000095017025105920-lnkb-ex32.htm.pdf?AWSAccessKeyId=AKIAZ2SDT5DUYIU3G434&Signature=eqpi%2Bj9ObTS%2BJE%2BSNUh8iOgr2zg%3D&Expires=1761229440",
        "page_count": 1,
        "language": "en"
      },
      {
        "report_id": "f_haBmMwT4WN7tXrt8rj9eA3",
        "file_title": "Quarterly Report",
        "file_title_en": "Quarterly Report",
        "clickable_link": "https://filing-reports.s3.amazonaws.com/reports-data/stock_us/2025/08/08/edgar-data-1756701-000095017025105920-lnkb-ex3_3.htm.pdf?AWSAccessKeyId=AKIAZ2SDT5DUYIU3G434&Signature=sF5ivZ9mkzJH%2FmlzWA6UUtWpr%2B8%3D&Expires=1761229440",
        "page_count": 12,
        "language": "en"
      },
      {
        "report_id": "f_haBmMwT4WN7tXrt8rj9eA3",
        "file_title": "Quarterly Report",
        "file_title_en": "Quarterly Report",
        "clickable_link": "https://filing-reports.s3.amazonaws.com/reports-data/stock_us/2025/08/08/edgar-data-1756701-000095017025105920-lnkb-ex31_1.htm.pdf?AWSAccessKeyId=AKIAZ2SDT5DUYIU3G434&Signature=NR3uP8vR8tT1A6GHwRgCV0%2FqgTQ%3D&Expires=1761229440",
        "page_count": 1,
        "language": "en"
      }
    ],
    "file_list_extract": [],
    "file_list_embadding": [],
    "billing_info": {
      "total_calls": 1,
      "total_options": 1,
      "total_charge": 1
    }
  },
  "message": "success"
}
```

> **Notes:**
>
> * All returned download links remain valid for **7 days** post-generation
> * Individual report failures are isolated and will not disrupt other report processing
> * Multiple query options can be specified simultaneously in a single request

***

#### Error Handling

All endpoints follow the standard error response format. When an error occurs, the API returns an appropriate HTTP status code along with a structured error response.

For detailed information about error codes, response formats, and troubleshooting guidelines, please refer to **Appendix A: Error Code Reference**.