# `POST /screener/events`

**Purpose:** Screen corporate event filings by company, filing date and Item code. Returns matching section summaries grouped by filing. Requires **Pro or higher**.

**Request:**

| Field | Type | Default | Notes |
|---|---|---|---|
| `tickers` | string[] | omitted | 1–100 symbols, each 1–32 characters. Case-insensitive; duplicates removed. Omitted = all available companies. |
| `start_date`, `end_date` | ISO date | omitted | Inclusive bounds on `filing_date`; `start_date` ≤ `end_date`. Either bound may be omitted. |
| `as_of_date` | ISO date | omitted | Exclude filings filed after this date: an `end_date` with no start. Must not be in the future or earlier than `start_date`. |
| `items` | string[] | omitted | 1–33 codes from [`GET /events/types`](/documents/get-eventstypes.md); duplicates removed. Omitted = all Items. |
| `item_match` | `"any"` \| `"all"` | `"any"` | Match at least one or all requested Item codes in a filing. Applies only when `items` is supplied. |
| `include_unresolved_amendments` | bool | `false` | Include standalone amendments without an associated original filing. |
| `exclude_likely_merged` | bool | `false` | Exclude filings with `merge_status="likely"`. |
| `page` | int ≥ 1 | 1 | |
| `page_size` | int 1–10 | 5 | Filings per page. |
| `detail` | string | `"full"` | Full and minimal views only: `"light"` returns the minimal view. See [Response detail](/documents/responses.md#response-detail). |

**Pagination cap:** `page × page_size ≤ 500` (422 above it). When the next page would pass the cap, `has_more` is `false`, `next_page` is `null`, and `_warnings` says the limit was reached.

**Response:**

| Field | Meaning |
|---|---|
| `page`, `page_size`, `has_more`, `next_page` | Pagination. `next_page` is `null` on the last page. |
| `filings` | [Event filing objects](/documents/event-objects.md#event-filing-object), each with a `sections` array of matching [event section objects](/documents/event-objects.md#event-section-object). Empty results return `[]`. |
| `credits_used`, `_warnings` | Credits charged and optional [event warnings](/documents/event-objects.md#event-warnings). |

Results are ordered by `filing_date` descending. Each issuer and accession appears once, including when several share-class symbols match. With `items`, only matching sections are returned; the filing's `items` and `items_declared` remain complete. Original text, `prior` and `amendments` are on [`POST /events/filing`](/documents/post-eventsfiling.md).

**Credits:** **65–280 per page**, using the [Credit formula (`/screener/events`)](/documents/post-screenerevents.md#credit-formula-screenerevents) formula.

**Errors:** `422 VALIDATION_ERROR`, `402 CREDITS_INSUFFICIENT`, `403 PLAN_TIER_INSUFFICIENT` below Pro, `504 EVENTS_QUERY_TIMEOUT` at the 30-second query timeout (charged).

**Example Request:**

```json
{
  "tickers": [
    "CNP"
  ],
  "start_date": "2023-01-01",
  "end_date": "2023-01-31",
  "items": [
    "5.02"
  ],
  "page": 1,
  "page_size": 5
}
```

**Example Response:**

```json
{
  "page": 1,
  "page_size": 5,
  "has_more": false,
  "next_page": null,
  "filings": [
    {
      "id": 4688,
      "ticker": "CNP",
      "issuer_cik": "0001130310",
      "accession_number": "0001130310-23-000002",
      "form_type": "8-K",
      "filing_date": "2023-01-03",
      "period_of_report": "2023-01-03",
      "items": [
        "5.02",
        "7.01",
        "9.01"
      ],
      "items_declared": [
        "5.02",
        "7.01",
        "9.01"
      ],
      "merge_status": "confirmed",
      "source_url_prefix": "https://www.sec.gov/Archives/edgar/data/1130310/000113031023000002/",
      "sections": [
        {
          "item": "5.02",
          "title": "Departure of Directors or Certain Officers; Election of Directors; Appointment of Certain Officers; Compensatory Arrangements of Certain Officers",
          "summary": "On January 3, 2023, CenterPoint Energy, Inc. announced a new organizational structure effective immediately. Chief Executive Officer David J. Lesar continues in his role; President and Chief Operating Officer Jason P. Wells continues and will also serve as Chief Financial Officer until a successor is appointed…",
          "source_accession": "0001130310-23-000028",
          "source_filing_date": "2023-02-21",
          "restated": "modified",
          "source_locator": "../000113031023000028/cnp-20230217.htm"
        }
      ]
    }
  ],
  "credits_used": 65
}
```

## Credit formula (`/screener/events`)

`POST /screener/events` charges per page:

```text title="Formula"
credits = max(65, 200
              − tickerDiscount        // 100 − n distinct requested tickers; 0 when omitted
              − shortWindowDiscount   // 40 when both dates are supplied and differ by ≤ 90 days
              + fullHistorySurcharge) // 80 when start_date is omitted
```

Range **65–280**.

| Request scope | Credits per page |
|---|---:|
| One ticker, both dates within 90 days | 65 |
| All companies, both dates within 90 days | 160 |
| All companies, a longer range with `start_date` | 200 |
| All companies, no `start_date` | 280 |

Charged even when `filings` is empty, and on `504 EVENTS_QUERY_TIMEOUT`. No charge on validation, authentication, endpoint-tier, insufficient-credit or rate-limit errors.