# Get Report List by Question

#### Endpoint

```
POST /v1/ai_chat/get_report_list_by_question_and_related_info
```

[**Try it out in API Playground →**](https://api.orbitfin.ai/docs#/AI%20Chat/GetReportListByQuestionAndRelatedInfo_v1_ai_chat_get_report_list_by_question_and_related_info_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                                          |
| ------------------ | -------------- | -------- | ---------------------------------------------------- |
| `keywords`         | string         | Yes      | The question posed by the user                       |
| `report_type_list` | array\[string] | No       | List of report types to narrow down search results   |
| `start_date`       | string         | No       | Start date for the search, formatted as `YYYY-MM-DD` |
| `end_date`         | string         | No       | End date for the search, formatted as `YYYY-MM-DD`   |
| `market`           | array\[string] | No       | List of markets to filter search results             |
| `sector_list`      | array\[string] | No       | List of sectors to narrow down search results        |
| `exchange_list`    | array\[string] | No       | List of exchanges to filter search results           |
| `country_list`     | array\[string] | No       | List of countries to narrow down search results      |

> **Note:** Options for `market`, `exchange_list`, `country_list`, and `sector_list` are included in **Appendix B: Metainfo**.

#### Example Request

```bash
curl -X 'POST' \
  'https://api.orbitfin.ai/v1/ai_chat/get_report_list_by_question_and_related_info' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "keywords": "Please help me analyze the performance of Apple stock over the past year",
  "report_type_list": [],
  "start_date": "2024-10-24",
  "end_date": "2025-10-24",
  "market": [],
  "sector_list": [],
  "exchange_list": [],
  "country_list": []
}'
```

***

### Response

#### Response Fields

**Top-Level Fields**

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

**Data Object**

| Field        | Type   | Description                                 |
| ------------ | ------ | ------------------------------------------- |
| `table_data` | array  | Array of report objects matching the query  |
| `total_data` | object | Summary statistics about the search results |

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

| Field                 | Type           | Description                                                   |
| --------------------- | -------------- | ------------------------------------------------------------- |
| `report_id`           | string         | Unique identifier for the report                              |
| `file_hash`           | string         | Hash value of the report file                                 |
| `report_title`        | string         | Title of the report                                           |
| `snippet`             | string         | Relevant text excerpt from the report                         |
| `report_type_id_list` | array\[string] | List of report type IDs                                       |
| `attachment_id`       | string         | Unique identifier for the attachment                          |
| `page`                | integer        | Page number where the relevant information is found           |
| `perm_id_list`        | array\[string] | List of permanent entity identifiers                          |
| `report_url`          | string         | S3 URL path to the report file                                |
| `reported_at`         | string         | Date when the report was published, formatted as `YYYY-MM-DD` |
| `score`               | integer        | Relevance score (0-100) indicating match quality              |

**Total Data Object (`data.total_data`)**

| Field                 | Type    | Description                                              |
| --------------------- | ------- | -------------------------------------------------------- |
| `total_company`       | integer | Total number of unique companies in results              |
| `total_document`      | integer | Total number of documents found                          |
| `total_document_type` | integer | Total number of unique document types                    |
| `dataset`             | string  | Dataset identifier                                       |
| `max_score`           | integer | Highest relevance score in results                       |
| `min_score`           | integer | Lowest relevance score in results                        |
| `latest_report_date`  | string  | Most recent report date, formatted as `YYYY-MM-DD`       |
| `oldest_report_date`  | string  | Oldest report date in results, formatted as `YYYY-MM-DD` |

#### Example Response

```json
{
  "status_code": 200,
  "data": {
    "table_data": [
      {
        "report_id": "f_0fVY5cTHqSbJnLrWy7FkfT",
        "file_hash": "P3UM8gXH",
        "report_title": "Annual Report",
        "snippet": "Company Stock Performance\n\nThe following...",
        "report_type_id_list": [
          "10002"
        ],
        "attachment_id": "f_0fVY5cTHqSbJnLrWy7FkfT__P3UM8gXH",
        "page": 23,
        "perm_id_list": [
          "1-4295905573"
        ],
        "report_url": "s3://filing-reports/reports-data/stock_us/2025/10/31/edgar-data-320193-000032019325000079-aapl-20250927.htm.pdf",
        "reported_at": "2025-10-31",
        "score": 100
      },
      {
        "report_id": "o_dutEbR7Dr2dNWOEW4QDhzp",
        "file_hash": "QZVWPAbc",
        "report_title": "Apple 2025 Environmental Progress Report",
        "snippet": "Sustainalytics\n\nAnnualReview\n\nApple Inc....",
        "report_type_id_list": [
          "10076"
        ],
        "attachment_id": "o_dutEbR7Dr2dNWOEW4QDhzp__QZVWPAbc",
        "page": 93,
        "perm_id_list": [
          "1-4295905573"
        ],
        "report_url": "s3://official-reports/data-system/3993BC1C138109A805CDE0B1F9442531.pdf",
        "reported_at": "2025-07-31",
        "score": 70
      }
    ],
    "total_data": {
      "total_company": 1,
      "total_document": 33,
      "total_document_type": 8,
      "dataset": "0+",
      "max_score": 100,
      "min_score": 30,
      "latest_report_date": "2025-11-14",
      "oldest_report_date": "2025-06-10"
    }
  },
  "message": "success"
}
```

***

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