Report List

Get Report List by Question

Endpoint

POST /v1/company_report/report_search

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
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: 50)
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:

4KB

US Form Type.csv

Open

Example Request

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

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