> 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=실적
```