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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orbitfin.ai/orbit-api-reference/api/file-download.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.