# Report List

## Get Report List by Question

#### Endpoint

```
POST /v1/company_report/report_search
```

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

#### Description

This API enables users to retrieve a curated list of relevant reports by submitting a natural language question. The system analyzes the question's intent and returns matching reports filtered by specified criteria such as date range, market, sector, and report type. This endpoint is ideal for quickly discovering pertinent financial documents and research materials without needing to know exact report titles or identifiers.

***

### 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                                                     |
| --------------------- | -------------- | -------- | --------------------------------------------------------------- |
| `orbit_entity_id`     | string         | Yes      | Unique company identifier for precise query of specific reports |
| `start_time`          | string         | No       | Start date for the search, formatted as `YYYY-MM-DD`            |
| `end_time`            | string         | No       | End date for the search, formatted as `YYYY-MM-DD`              |
| `report_type_list`    | array\[string] | No       | List of report type IDs to filter results (see Appendix B)      |
| `limit`               | integer        | No       | Number of results per page (default: 20, max: 100)              |
| `offset`              | integer        | No       | Offset for pagination (default: `0`)                            |
| `option`              | dict           | No       | Optional extension.                                             |
| `option.us_form_type` | array\[string] | No       | Type of U.S. exchange.                                          |

> **Notes:**
>
> * Time range cannot exceed one year
> * ECM report types (`10122`, `10283`, `10284`, `10311`) are not supported by this endpoint
> * `report_type_list` supports both single type string or multiple types in array format
> * Report type options are detailed in **Appendix B: Metainfo**

#### Parameter US Form Type Reference:

{% file src="/files/Rl5BEpJtpbgoOdZ9pSZ1" %}

#### Example Request

```bash
curl -X 'POST' \
  'https://api.orbitfin.ai/v1/company_report/report_search' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "orbit_entity_id": "1-5065300786",
  "start_time": "2024-06-01",
  "end_time": "2024-08-31",
  "report_type_list": ["10002"],
  "limit": 25,
  "offset": 0
}'
```

***

### Response

#### Response Fields

**Top-Level Fields**

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

**Data Object**

| Field        | Type   | Description                                |
| ------------ | ------ | ------------------------------------------ |
| `reports`    | array  | Array of report objects matching the query |
| `pagination` | object | Pagination information for result set      |

**Report Object (`data.reports[]`)**

| Field             | Type           | Description                                            |
| ----------------- | -------------- | ------------------------------------------------------ |
| `id`              | string         | Unique identifier for the report                       |
| `orbit_entity_id` | array\[string] | List of company identifiers associated with the report |
| `date`            | string         | Report publication date, formatted as `YYYY-MM-DD`     |
| `title`           | string         | Title of the report                                    |
| `lang`            | string         | Language code of the report (e.g., `en` for English)   |

**Pagination Object (`data.pagination`)**

| Field      | Type    | Description                                                   |
| ---------- | ------- | ------------------------------------------------------------- |
| `total`    | integer | Total number of reports matching the search criteria          |
| `limit`    | integer | Number of results returned per page                           |
| `offset`   | integer | Current offset position in the result set                     |
| `has_more` | boolean | Indicates whether more results are available (`true`/`false`) |

#### Example Response

```json
{
  "status_code": 200,
  "data": {
    "reports": [
      {
        "id": "f_6Yo8kDJdYK3qawXbLWVYmy",
        "orbit_entity_id": [
          "1-5065300786"
        ],
        "date": "2024-06-04",
        "title": "Annual report - English",
        "lang": "en"
      }
    ],
    "pagination": {
      "total": 1,
      "limit": 25,
      "offset": 0,
      "has_more": false
    }
  },
  "message": "Report search successful"
}
```

***

#### 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/report-list.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.