# vaers.globalpatientsafety.com signals API

For LLM / machine clients. Human UI is https://vaers.globalpatientsafety.com/.
OpenAPI 3 schema: https://vaers.globalpatientsafety.com/openapi.json
Machine index: https://vaers.globalpatientsafety.com/llms.txt

VAERS reports are voluntary. Counts are reporting, not incidence.
Disproportionate reporting is a **hypothesis**, not evidence of causation.
Always read `n` and `eb05`.

The column in the parquet is `drug`. It holds the VAERS vaccine name
(`VAX_NAME`). `vaccine=` and `drug=` are the same parameter. If both are
set and they differ, the response is HTTP 400.

## GET /signals

No API key. CORS `*`.

```
GET /signals?vaccine=COVID19&event=Myocarditis
GET /signals?event=Myocarditis&limit=20
GET /signals?q=Myocarditis
```

| Parameter | Meaning |
|-----------|---------|
| `vaccine` | Vaccine name, or an exact vaccine type such as `COVID19` (every product of that type). |
| `drug` | Same as `vaccine`. |
| `event` | MedDRA preferred term, exact name or a substring of at least 3 characters. |
| `q` | When `vaccine` and `event` are both omitted, the union of vaccine-name matches and event-name matches. `format=class` uses `q` as the vaccine seed when `vaccine` is omitted. |
| `format` | `json` (default), `csv`, `series`, `profile`, `brief`, `class`. |
| `sort` | `eb05` (default), `n`, or `latest`. `trend` is HTTP 400. This service does not derive a trend. |
| `order` | `desc` (default) or `asc`. |
| `limit` | Default 50. Maximum 500. |
| `offset` | Default 0. |
| `min_eb05` | Keep pairs whose peak EB05 is at least this number. Applied after the aggregate and before the total. Not a number, or below 0, is HTTP 400. |
| `min_n` | Keep pairs whose `n` is at least this number. Same timing as `min_eb05`. |

A missing `vaccine`, `event`, and `q` is HTTP 400.
A query shorter than 3 characters that is not an exact name or an
abbreviation is HTTP 400 (`query is too short`).
An unknown vaccine or event is HTTP 200 and an empty list, not 500.
An unknown `format` is HTTP 400 with `error` and `allowed`.
`format=label` and `format=pdf` are in that 400. This service does not
serve FDA labels or PDFs.

`+` in the query string is a space.

### Default JSON

A JSON array of pair objects. Headers:

| Header | Meaning |
|--------|---------|
| `X-Total-Count` | Pairs matched, before limit/offset. |
| `X-Limit` | Page size. |
| `X-Offset` | Rows skipped. |
| `X-VAERS-Through` | Latest quarter in the file. |
| `X-VAERS-Build` | `api-<12 hex>` is the sha256 of `scripts/signals_api.R`. `src-<sha>` is the first line of a VERSION file written on the server at deploy. The header does not use `git rev-parse`. |
| `X-VAERS-Hypothesis` | The voluntary-reporting sentence. |
| `Cache-Control` | `public, max-age=60`. |

Each row:

| Field | Meaning |
|-------|---------|
| `vaccine`, `drug`, `vax_name` | All three are the vaccine name (`VAX_NAME`). They are not the vaccine type. |
| `vax_type` | Name with the parenthetical product suffix removed. `INFLUENZA3` becomes `INFLUENZA`. `COVID19` stays `COVID19`. |
| `event` | MedDRA preferred term. |
| `n` | Sum of quarterly `observed`. Rolling windows overlap, so this is **not** a count of unique reports. Same number as Obs in the app. |
| `eb05` | Peak quarterly EB05 (`max(eb05)`) among quarters with `n_methods_flagged >= 2`. Same number as Peak EB05 in the app. Raw quarterly EB05, not the EWMA. |
| `eb05_peak_pre2021` | Highest quarterly EB05 before `2021Q1` on the full series, including quarters below the flagged floor. Null when the pair has no pre-2021 quarter. Not a new statistic. |
| `eb05_peak_pre2021_quarter` | Earliest quarter that attains `eb05_peak_pre2021`. |
| `eb05_peak_quarter` | Earliest quarter that attains the full-series maximum EB05. This can differ from the quarter of `eb05` when an unflagged quarter is higher. |
| `peak_in_covid_era` | True when `vax_type` is not `COVID19` and `eb05_peak_quarter` is inside `2021Q1`–`2022Q4`. |
| `background_note` | One sentence. COVID-19 vaccines: their own volume dominates the 2021–2022 background. Other vaccines with `peak_in_covid_era`: that peak falls in the window when COVID-19 reports shrank the background. |
| `ewma_eb05` | Peak EWMA EB05. A different number from `eb05`. |
| `n_methods_max` | Highest `n_methods_flagged` across quarters. |
| `quarters_flagged` | Quarters where `is_signal_any` is true. |
| `first_quarter`, `latest_quarter` | First and last quarter in the filtered rows. |
| `emerging` | True when `first_quarter` is within the last four quarters of the file. |

Only pairs with `n_methods_flagged >= 2` in a quarter enter the aggregate.
That is the same floor as the app.

### format=series

One pair: the highest peak EB05 when several pairs match. Needs a vaccine
and an event, or `q`. Body is an object with `quarters[]` of
`quarter`, `n`, `eb05`, `eb50`, `eb95`, `prr`, `ror`, `ic`,
`n_methods_flagged`, `is_signal_any`. `ic025` is included on a quarter
when the parquet has that column. Pair rows do not carry `prr`, `ror`,
`ic`, or `ic025`. There is no `ebgm` column. `eb50` is the quarterly
median, not an EBGM.

### format=profile

Object with `kind` (`vaccine`, `event`, or `pair`), `n_pairs`, `hypothesis`,
and `pairs` (the page).

### format=class

Products of the same vaccine type. `vaccine=COVID19` returns every COVID-19
product, not only the string `COVID19`. Optional `event=` keeps that event.
Body includes `vax_type`, `vaccines`, `n_pairs`, `pairs`.

### format=brief

`text/plain` markdown. Includes the hypothesis sentence, the filters
that were applied (`Filters: none` when there were none), how many rows
those filters left out, and how many rows this page left out. It also
notes that `n` is not unique reports, and that `n_unique` is not in
this extract. The signals parquet has no VAERS report id. It names
`eb05_peak_pre2021` and `peak_in_covid_era` on each pair. It does not
contain clinical-trial identifiers.

`n_unique` (distinct VAERS ids) and `background=no_covid` (GPS refit
after dropping COVID-19 vaccine reports) are not served. Both need a
pipeline recompute. This API does not invent either number.

### format=csv

The same columns as the JSON rows, for the current page.

## What this API does not do

No FDA label status, no novelty flag, no substance or ATC class, no PDF,
no ClinicalTrials.gov join, and no NCT ids. Those belong to other hosts.
`format=label` and `format=pdf` return 400.

`sort=trend` returns 400. The app does not derive a trend, so the API
does not invent one. Pair rows omit `ebgm`, `prr`, `ror`, and `ic025`.
`prr`, `ror`, and `ic` are quarterly values on `format=series`. `ic025`
is on those quarters only when the parquet has the column. There is no
`ebgm` column. `eb50` on a quarter is the median.

## MCP

These tools are on the existing faers.mobi MCP server
(https://faers.mobi/mcp). This host does not serve `/mcp`. Each tool
calls this same `GET /signals`.

| Tool | Call |
|------|------|
| `get_vaers` | vaccine and/or event. `format` is json, series, profile, or class. |
| `vaers_search_vaccine` | vaccine, optional event. JSON pair list. |
| `vaers_get_signal` | vaccine and event. JSON pair list. |
| `vaers_get_profile` | vaccine. `format=profile`. |

## ChatGPT Actions

Paste-ready import: https://vaers.globalpatientsafety.com/chatgpt.md

Schema URL: `https://vaers.globalpatientsafety.com/openapi.json` (auth: none).

## Examples

```
curl -sS 'https://vaers.globalpatientsafety.com/signals?vaccine=COVID19&event=Myocarditis&limit=5'
curl -sS 'https://vaers.globalpatientsafety.com/signals?vaccine=COVID19&event=Myocarditis&format=brief'
curl -sS 'https://vaers.globalpatientsafety.com/signals?event=Myocarditis&format=profile&limit=5'
curl -sS 'https://vaers.globalpatientsafety.com/openapi.json'
```