Get Report List by Question

Endpoint

POST /v1/ai_chat/get_report_list_by_question_and_related_info

Try it out in API Playground →

---

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

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

{
  "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.