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

# POST /timeline

> Material events for a date range.

## Use case

Get material events (SEC 8-K filings — leadership changes, M\&A, financial events) for a company over a specific date range. Useful for due-diligence pulls, "what happened during this person's tenure"-style queries, and event-driven monitoring.

## Request

<ParamField body="company" type="string" required>
  Company name or entity key. 2–200 characters.
</ParamField>

<ParamField body="start" type="string" required>
  Period start, `YYYY-MM` format.
</ParamField>

<ParamField body="end" type="string">
  Period end, `YYYY-MM` format. Defaults to today.
</ParamField>

<ParamField body="types" type="array">
  Filter by event type (e.g., `["8-K Item 1.01", "8-K Item 2.02"]`). Empty array returns all types.
</ParamField>

## Response

<ResponseField name="entity" type="object">
  `key` + `name` of the resolved entity.
</ResponseField>

<ResponseField name="period" type="object">
  `start` + `end` (echoed from request, with `end` filled if defaulted).
</ResponseField>

<ResponseField name="summary" type="string">
  Human-readable summary, e.g., `"2 notable events during this period"`.
</ResponseField>

<ResponseField name="events" type="array">
  Up to 20 events, ordered by `filing_date` DESC. Each event:

  <Expandable title="event fields">
    <ResponseField name="event.date" type="string">SEC filing date, `YYYY-MM-DD`.</ResponseField>
    <ResponseField name="event.type" type="string">SEC event type, e.g., `"Operating Results"`, `"Departure of Directors"`.</ResponseField>
    <ResponseField name="event.headline" type="string | null">Filing headline (often null for routine 8-K item types).</ResponseField>
    <ResponseField name="event.description" type="string | null">Longer description (often null for routine filings).</ResponseField>
    <ResponseField name="event.item" type="string | null">SEC 8-K item number, e.g., `"2.02"`.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metrics" type="object">Placeholder for future quantitative metrics over the period.</ResponseField>

<ResponseField name="resolution" type="object">Provenance — see [Citation Contract](/citation-contract).</ResponseField>

## Code samples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.getbeta.io/api/v1/timeline \
    -H "Authorization: Bearer $BETA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"company": "Microsoft", "start": "2026-01", "end": "2026-05"}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.getbeta.io/api/v1/timeline', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BETA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company: 'Microsoft',
      start: '2026-01',
      end: '2026-05'
    })
  });
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.post(
      'https://api.getbeta.io/api/v1/timeline',
      headers={'Authorization': f'Bearer {os.environ["BETA_API_KEY"]}'},
      json={'company': 'Microsoft', 'start': '2026-01', 'end': '2026-05'}
  )
  ```
</CodeGroup>

## Live response

```json theme={null}
{
  "entity": {
    "key": "microsoft",
    "name": "Microsoft Corporation"
  },
  "period": { "start": "2026-01", "end": "2026-05" },
  "summary": "2 notable events during this period",
  "events": [
    {
      "date": "2026-04-29",
      "type": "Operating Results",
      "headline": null,
      "description": null,
      "item": "2.02"
    },
    {
      "date": "2026-01-28",
      "type": "Operating Results",
      "headline": null,
      "description": null,
      "item": "2.02"
    }
  ],
  "metrics": {},
  "resolution": { "source": "curated", "confidence": 1 }
}
```

<Note>
  Item 2.02 ("Results of Operations") filings often have null `headline` and `description` — these are routine quarterly earnings releases. For deeper inspection, follow up with the SEC filing URL or a dedicated financials data source.
</Note>

## Errors

| Status | Body                                                               | When               |
| ------ | ------------------------------------------------------------------ | ------------------ |
| `400`  | `{"error": "Start date required (YYYY-MM format)"}`                | Missing `start`    |
| `404`  | `{"error": "Company not found", "code": "NOT_FOUND"}`              | No entity resolved |
| Other  | See [`/validate`](/endpoints/validate#errors) for the standard set |                    |