Skip to main content
POST
/
api
/
v1
/
timeline
POST /timeline
curl --request POST \
  --url https://api.getbeta.io/api/v1/timeline \
  --header 'Content-Type: application/json' \
  --data '
{
  "company": "<string>",
  "start": "<string>",
  "end": "<string>",
  "types": [
    {}
  ]
}
'
{
  "entity": {},
  "period": {},
  "summary": "<string>",
  "events": [
    {
      "event.date": "<string>",
      "event.type": "<string>",
      "event.headline": {},
      "event.description": {},
      "event.item": {}
    }
  ],
  "metrics": {},
  "resolution": {}
}

​
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

​
company
string
required
Company name or entity key. 2–200 characters.
​
start
string
required
Period start, YYYY-MM format.
​
end
string
Period end, YYYY-MM format. Defaults to today.
​
types
array
Filter by event type (e.g., ["8-K Item 1.01", "8-K Item 2.02"]). Empty array returns all types.

​
Response

​
entity
object
key + name of the resolved entity.
​
period
object
start + end (echoed from request, with end filled if defaulted).
​
summary
string
Human-readable summary, e.g., "2 notable events during this period".
​
events
array
Up to 20 events, ordered by filing_date DESC. Each event:
​
metrics
object
Placeholder for future quantitative metrics over the period.
​
resolution
object
Provenance — see Citation Contract.

​
Code samples

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"}'

​
Live response

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

​
Errors

StatusBodyWhen
400{"error": "Start date required (YYYY-MM format)"}Missing start
404{"error": "Company not found", "code": "NOT_FOUND"}No entity resolved
OtherSee /validate for the standard set