> For the complete documentation index, see [llms.txt](https://docs.alpha-lenz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alpha-lenz.com/en/api-reference/public-api/research.md).

# Research

Access research reports from securities firms.

**Required Scope:** `read:research` or `read:all`

## List Research Reports

Get research reports with filtering and pagination.

```
GET /api/public/v1/research/reports
```

### Query Parameters

| Parameter           | Type    | Description                                                 |
| ------------------- | ------- | ----------------------------------------------------------- |
| `page`              | integer | Page number (default: 1)                                    |
| `page_size`         | integer | Items per page (1-100, default: 20)                         |
| `securities_firm`   | string  | Filter by securities firm                                   |
| `stock_name`        | string  | Filter by stock name                                        |
| `report_type`       | string  | Filter by type: "company\_analysis" or "industry\_analysis" |
| `industry_category` | string  | Filter by industry category                                 |
| `start_date`        | date    | Filter from date (YYYY-MM-DD)                               |
| `end_date`          | date    | Filter to date (YYYY-MM-DD)                                 |
| `title`             | string  | Search in report title                                      |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports?stock_name=삼성전자&page_size=10" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "reports": [
    {
      "id": 456,
      "title": "Samsung Electronics - 4Q23 Preview",
      "report_date": "2024-01-10",
      "report_type": "company_analysis",
      "securities_firm": "미래에셋증권",
      "stock_name": "삼성전자",
      "industry_category": "반도체",
      "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
    }
  ],
  "total": 125,
  "page": 1,
  "page_size": 10,
  "has_next": true
}
```

***

## Get Research Report

Get detailed information about a specific research report.

```
GET /api/public/v1/research/reports/{report_id}
```

### Path Parameters

| Parameter   | Type    | Description        |
| ----------- | ------- | ------------------ |
| `report_id` | integer | Research report ID |

### Example Request

```bash
curl -X GET "https://api.alpha-lenz.com/api/public/v1/research/reports/456" \
     -H "X-API-Key: ak_your_key"
```

### Response

```json
{
  "id": 456,
  "title": "Samsung Electronics - 4Q23 Preview",
  "report_date": "2024-01-10",
  "report_type": "company_analysis",
  "securities_firm": "미래에셋증권",
  "stock_name": "삼성전자",
  "industry_category": "반도체",
  "s3_key": "reports/2024/01/456.pdf",
  "cdn_url": "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
}
```

### Downloading Reports

Use the `cdn_url` field to download the PDF report:

```bash
curl -O "https://static.alpha-lenz.com/reports/2024/01/456.pdf"
```

### Report Types

| Type                | Description                 |
| ------------------- | --------------------------- |
| `company_analysis`  | Individual company analysis |
| `industry_analysis` | Industry/sector analysis    |

### Pagination

Use `page` and `page_size` for pagination. Check `has_next` to see if there are more results:

```bash
# First page
GET /research/reports?page=1&page_size=20

# Second page
GET /research/reports?page=2&page_size=20
```

### Filtering Examples

**By Securities Firm:**

```
GET /research/reports?securities_firm=미래에셋증권
```

**By Date Range:**

```
GET /research/reports?start_date=2024-01-01&end_date=2024-01-31
```

**By Industry:**

```
GET /research/reports?industry_category=반도체
```

**Title Search:**

```
GET /research/reports?title=실적
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.alpha-lenz.com/en/api-reference/public-api/research.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.