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

# GET /events — Retrieve Real-Time SEC Market Events

> Retrieve real-time market events from SEC filings. Supports filtering by ticker, event type, date range, and impact score. Includes single-event lookup.

The `/events` endpoint is the core of the Useellis News API, returning real-time market events sourced from SEC EDGAR filings. Each event includes a structured headline, an AI-generated summary, the originating SEC filing reference, and a 5-bar impact signal — giving your integration everything it needs to act on material corporate developments without touching the raw filing.

## Endpoint

```
GET https://api.insighthread.com/v1/events
```

## Query Parameters

**ticker** `string`

Filter events to a single company by its ticker symbol. Case-insensitive. Example: `AAPL`, `NVDA`, `MSFT`.

**event\_type** `string`

Filter by event category. Must match a value from the [Event Categories](https://docs.useellis.com/api/event-categories.md) reference exactly. Example: `Mergers and Acquisitions`. URL-encode values containing spaces or slashes.

**impact\_min** `integer`

Return only events with an impact score at or above this threshold. Accepts integers `1` through `5`. For example, passing `4` returns only `Major` (4) and `Critical` (5) events. Omit to return all impact levels.

**direction** `string`

Filter events by the direction of their impact signal. Accepted values: `positive`, `negative`, `neutral`.

**from** `string`

Return only events published at or after this timestamp. Must be a valid ISO 8601 datetime string. Example: `2026-01-01T00:00:00Z`.

**to** `string`

Return only events published at or before this timestamp. Must be a valid ISO 8601 datetime string. Use in combination with `from` to define a fixed time window.

**limit** `integer` (default: 20)

Number of events to return per page. Default is `20`; maximum is `100`.

**cursor** `string`

Pagination cursor returned in the `next_cursor` field of a previous response. Pass this value to retrieve the next page of results. Omit for the first request.

## Example Request

The following request retrieves up to 5 high-impact events for NVDA with an impact score of 3 or above:

```bash theme={null}
curl "https://api.insighthread.com/v1/events?ticker=NVDA&impact_min=3&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Example Response

```json theme={null}
{
  "data": [
    {
      "id": "evt_8k101_nvda_apr14",
      "ticker": "NVDA",
      "event_type": "Mergers and Acquisitions",
      "headline": "NVIDIA acquires Run:ai in $700M all-cash transaction",
      "summary": "NVIDIA Corporation has entered into a definitive agreement to acquire Run:ai, an AI workload management platform, for approximately $700 million in cash. The acquisition is expected to close in the second half of fiscal 2026, subject to regulatory approvals.",
      "primary_filing": "8-K (1.01)",
      "secondary_filing": null,
      "filing_url": "https://sec.gov/Archives/edgar/data/1045810/000104581026000041/0001045810-26-000041-index.htm",
      "impact": {
        "score": 4,
        "direction": "positive",
        "label": "Major",
        "bars": 4
      },
      "published_at": "2026-04-14T09:18:33Z"
    },
    {
      "id": "evt_8k103_iobt_mar31",
      "ticker": "IOBT",
      "event_type": "Bankruptcy/Liquidation",
      "headline": "IO Biotech files Chapter 7, ceases all operations",
      "summary": "IO Biotech has filed for Chapter 7 bankruptcy protection and will cease all operations immediately. The company's assets are to be liquidated under the supervision of a court-appointed trustee following the failure of its lead oncology program.",
      "primary_filing": "8-K (1.03)",
      "secondary_filing": "15-12B",
      "filing_url": "https://sec.gov/Archives/edgar/data/1834585/000183458526000008/0001834585-26-000008-index.htm",
      "impact": {
        "score": 5,
        "direction": "negative",
        "label": "Critical",
        "bars": 5
      },
      "published_at": "2026-03-31T14:22:08Z"
    }
  ],
  "next_cursor": "eyJpZCI6ImV2dF84azEwM19pb2J0X21hcjMxIiwiZGlyIjoibmV4dCJ9",
  "total": 47
}
```

## Response Fields

**data** `array`

Array of event objects matching the query. May be empty if no events match the specified filters.

**Event object fields**

**id** `string`

Unique identifier for the event. Format: `evt_{filing_type}_{ticker}_{date}`.

**ticker** `string`

Ticker symbol of the company associated with this event.

**event\_type** `string`

Event category. One of 35+ possible values. See the [Event Categories](https://docs.useellis.com/api/event-categories.md) reference for the complete list.

**headline** `string`

Short, human-readable headline summarizing the event in a single sentence.

**summary** `string`

AI-generated summary of the event, typically 1–3 sentences. Grounded in the content of the SEC filing.

**primary\_filing** `string`

The primary SEC filing type and item section that triggered this event. Example: `8-K (1.01)`, `10-Q`, `Form 4`.

**secondary\_filing** `string | null`

A secondary SEC filing associated with the same event, if applicable. `null` if there is no secondary filing.

**filing\_url** `string`

Direct URL to the original filing on SEC EDGAR. Use this to link users to the primary source.

**impact** `object`

Impact signal for this event. Contains a score, directional label, and human-readable severity label.

**impact fields**

**impact.score** `integer`

Numerical impact score from `1` (Minor) to `5` (Critical). Maps directly to `bars`.

**impact.direction** `string`

Directional assessment of the event's impact: `positive`, `negative`, or `neutral`.

**impact.label** `string`

Human-readable severity label corresponding to the score: `Minor`, `Moderate`, `Significant`, `Major`, or `Critical`.

**impact.bars** `integer`

Visual bar count from `1` to `5`, identical to `score`. Maps to the 5-bar impact indicator in the Useellis UI.

**published\_at** `string`

ISO 8601 timestamp indicating when Useellis published this event, within 90 seconds of the SEC filing being accepted by EDGAR.

**next\_cursor** `string | null`

Opaque pagination cursor pointing to the next page of results. Pass this value as the `cursor` query parameter on your next request. Returns `null` when the current page is the last page.

**total** `integer`

Total number of events matching the query across all pages.

## Get a Single Event

Retrieve a single event by its unique identifier. Use this endpoint to refresh or re-fetch a specific event after you have already stored its `id`.

```
GET https://api.insighthread.com/v1/events/{id}
```

### Path Parameters

**id** `string` *required*

The unique event identifier. Obtained from the `id` field of any event object returned by `GET /events` or `GET /companies/{ticker}`. Example: `evt_8k101_nvda_apr14`.

### Example Request

```bash theme={null}
curl "https://api.insighthread.com/v1/events/evt_8k101_nvda_apr14" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example Response

```json theme={null}
{
  "id": "evt_8k101_nvda_apr14",
  "ticker": "NVDA",
  "event_type": "Mergers and Acquisitions",
  "headline": "NVIDIA acquires Run:ai in $700M all-cash transaction",
  "summary": "NVIDIA Corporation has entered into a definitive agreement to acquire Run:ai, an AI workload management platform, for approximately $700 million in cash. The acquisition is expected to close in the second half of fiscal 2026, subject to regulatory approvals.",
  "primary_filing": "8-K (1.01)",
  "secondary_filing": null,
  "filing_url": "https://sec.gov/Archives/edgar/data/1045810/000104581026000041/0001045810-26-000041-index.htm",
  "impact": {
    "score": 4,
    "direction": "positive",
    "label": "Major",
    "bars": 4
  },
  "published_at": "2026-04-14T09:18:33Z"
}
```

The single-event response returns the full Event object directly (not wrapped in a `data` array). All fields are identical to those described in the [Response Fields](#response-fields) section above. A `404 Not Found` is returned if the `id` does not exist.

## Pagination

The `/events` endpoint uses cursor-based pagination. When a response contains more results than the requested `limit`, the `next_cursor` field will be a non-null string. Pass that value as the `cursor` query parameter on your next request to retrieve the following page:

```bash theme={null}
# First request — no cursor
curl "https://api.insighthread.com/v1/events?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Subsequent request — pass next_cursor from the previous response
curl "https://api.insighthread.com/v1/events?limit=20&cursor=eyJpZCI6ImV2dF84azEwM19pb2J0X21hcjMxIiwiZGlyIjoibmV4dCJ9" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

When `next_cursor` is `null`, you have reached the last page of results. Cursors are stable for the lifetime of a query — the same cursor will always return the same next page for the same set of filters.

> [!NOTE]
>
> Rate limits vary by enterprise plan tier. Contact your account manager to confirm your request-per-minute and daily limits. If you exceed your limit, the API returns `429 Too Many Requests` — implement exponential backoff before retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.