> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chicago.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate Stock Report

> Generate a comprehensive stock report including financial analysis, valuation metrics, and AI-generated insights. This endpoint uses async job processing - submit your request, receive a job ID, then poll for results.

## How It Works

This endpoint uses **async job processing** for generating comprehensive stock reports:

1. **Submit Request**: POST the stock symbol to `/v1/stock-report`
2. **Receive Job ID**: Get a job ID and polling URL immediately
3. **Poll for Status**: Check `/v1/jobs/{job_id}` until status is `completed`
4. **Get Report URLs**: The completed job contains URLs to PDF, HTML, and JSON reports

<Note>
  Report generation typically takes 5-10 minutes. Reports include financial analysis, valuation metrics, AI-generated insights, and more.
</Note>

## Request Body

| Field    | Type    | Required | Default | Description                                     |
| -------- | ------- | -------- | ------- | ----------------------------------------------- |
| `symbol` | string  | Yes      | -       | Stock symbol (e.g., AAPL.O for Apple Inc)       |
| `force`  | boolean | No       | `false` | Force regeneration even if recent report exists |

<Warning>
  If `force` is `false` and a recent report exists (generated within the last 30 days), the cached report URLs will be returned immediately.
</Warning>

## Response (202 Accepted)

When the job is created:

```json theme={null}
{
  "job_id": "stock-a3522a92-87ed-4be0-a912-ad56ed6a8806",
  "status": "pending",
  "symbol": "AAPL.O",
  "force": false,
  "check_url": "/v1/jobs/stock-a3522a92-87ed-4be0-a912-ad56ed6a8806",
  "estimated_duration_seconds": 600,
  "message": "Stock report generation started for AAPL.O. Poll the check_url to get results."
}
```

## Completed Response

When the job completes, `GET /v1/jobs/{job_id}` returns:

```json theme={null}
{
  "job_id": "stock-a3522a92-87ed-4be0-a912-ad56ed6a8806",
  "job_type": "stock_report",
  "status": "completed",
  "result": {
    "success": true,
    "symbol": "AAPL.O",
    "pdf_url": "https://storage.example.com/reports/AAPL.O/report.pdf",
    "html_url": "https://storage.example.com/reports/AAPL.O/report.html",
    "json_url": "https://storage.example.com/reports/AAPL.O/report.json"
  }
}
```

## Example: Polling for Results

```javascript theme={null}
const response = await fetch('https://api.chicago.global/v1/stock-report', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ symbol: 'AAPL.O' })
});

const { job_id } = await response.json();

// Poll every 10 seconds (reports take ~15 minutes)
const interval = setInterval(async () => {
  const status = await fetch(
    `https://api.chicago.global/v1/jobs/${job_id}`,
    { headers: { 'Authorization': `Bearer ${API_KEY}` } }
  ).then(r => r.json());

  if (status.status === 'completed') {
    clearInterval(interval);
    console.log('PDF:', status.result.pdf_url);
    console.log('HTML:', status.result.html_url);
    console.log('JSON:', status.result.json_url);
  } else if (status.status === 'failed') {
    clearInterval(interval);
    console.error('Failed:', status.error);
  } else {
    console.log(`Status: ${status.status}, Progress: ${status.progress}`);
  }
}, 10000);
```

## Error Responses

| Status | Description                            |
| ------ | -------------------------------------- |
| 400    | Invalid symbol - no company data found |
| 401    | Invalid or missing API key             |
| 500    | Internal server error                  |

```json theme={null}
{
  "detail": "Invalid symbol 'INVALID': No company data found for this symbol."
}
```


## OpenAPI

````yaml POST /v1/stock-report
openapi: 3.1.0
info:
  title: Parallax API
  description: >-
    Financial data and portfolio analytics API. Analyze portfolios with
    multi-currency support, rebalancing, and comprehensive metrics.
  version: 1.0.0
servers:
  - url: https://api.chicago.global
security:
  - bearerAuth: []
paths:
  /v1/stock-report:
    post:
      tags:
        - Stock Reports
      summary: Generate Stock Report
      description: >-
        Generate a comprehensive stock report including financial analysis,
        valuation metrics, and AI-generated insights. This endpoint uses async
        job processing - submit your request, receive a job ID, then poll for
        results.
      operationId: generateStockReport
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StockReportRequest'
            example:
              symbol: AAPL.O
              force: false
      responses:
        '202':
          description: Job created successfully. Poll the check_url for results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StockReportJobResponse'
              example:
                job_id: stock-a3522a92-87ed-4be0-a912-ad56ed6a8806
                status: pending
                symbol: AAPL.O
                force: false
                check_url: /v1/jobs/stock-a3522a92-87ed-4be0-a912-ad56ed6a8806
                estimated_duration_seconds: 600
                message: >-
                  Stock report generation started for AAPL.O. Poll the check_url
                  to get results.
        '400':
          description: Invalid symbol
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: >-
                  Invalid symbol 'INVALID': No company data found for this
                  symbol.
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    StockReportRequest:
      type: object
      required:
        - symbol
      description: Request body for stock report generation
      properties:
        symbol:
          type: string
          description: Stock symbol (e.g., AAPL.O for Apple Inc)
          example: AAPL.O
        force:
          type: boolean
          default: false
          description: Force regeneration even if recent report exists
          example: false
    StockReportJobResponse:
      type: object
      properties:
        job_id:
          type: string
          description: Unique job identifier
        status:
          type: string
          enum:
            - pending
          description: Initial job status
        symbol:
          type: string
          description: Stock symbol being processed
        force:
          type: boolean
          description: Whether force regeneration was requested
        check_url:
          type: string
          description: URL to poll for job status
        estimated_duration_seconds:
          type: integer
          description: Estimated processing time in seconds
        message:
          type: string
          description: Human-readable status message
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token

````