List alerts, or the episodes they were folded into
List alerts, or the episodes they were folded into, through Ovok's Signals gateway.
List alerts, or the episodes they were folded into
| Method | Path |
|---|---|
GET | /v1/signals/api/alert |
- Sandbox: available
- Staging: available
- Production: unknown
The dashboard view.
By default this is one row per breach, in v1's alert shape plus every nest alert field, inside v1's paginate envelope (items, totalItems, page, totalPages, …) with nest's nextCursor beside it. Page with v1's page and limit (a page may start at most 10000 rows in), or walk with cursor: pass nextCursor back verbatim. sort is v1's time-desc (the default) or time-asc; ids narrows to those patients. It works whether or not the tenant has episodicAlerts. Without project it is tenant-wide: a per-facility view must send project, which keeps only patients stamped with it.
?episodes=true answers with episodes instead, as {items, nextCursor}: one row per clinical event, which opens on the first breaching reading, absorbs the rest, and closes on recovery, on going stale, or by hand. That grain REQUIRES project. It defaults to the tenant's feedCodes (PATCH /api/tenant), every code when it lists none; alerts have no code default.
codes, since and acknowledged filter either grain. until, page and ids are alerts only: sending one with episodes=true is a 422, not a filter that silently did nothing. status reads ACTIVE/RESOLVED for alerts and OPEN/CLOSED for episodes.
Episodes are newest first by sort: openedAt, the default, or lastFiringAt, the newest firing reading (the opening, for an episode that has none). since and the cursor use the same time. openedAt never changes, so walking every page lists each episode once. On lastFiringAt an episode that fires mid-walk moves above the cursor: it is never listed twice, but that walk misses it. A sort value from the other grain is a 422.
Through ovok
- Who can call it: Manager apps, and users whose access policy grants the capabilities.
- Capabilities, all required:
signals_alerts:read. Project admins have every capability; client applications get no admin bypass. - ovok sets
projectto your project, so you can leave it out. - If your access covers only some patients (anyone but project admins, manager or submitter apps, and anyone whose Patient access has no criteria), name them with
patientIdorids, each one you can read, at most 100. Signals then pages over just those patients, so pages and totals stay true. A patient is named by its Signals id, or by its Medplum Patient id where Signals takes arefId; ovok asks Signals which patient a Signals id is.
Request
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
episodes | boolean | No | Return episodes rather than the individual breaches they were folded from. An episode is one continuous clinical event for a (patient, code) pair: it opens on the first breaching reading, absorbs the rest, and closes on recovery, on going stale, or by hand. The default answers one row per breach, which is the duplication episodes exist to collapse. Requires project, and changes which of the filters below are accepted. |
patientId | string | No | — |
ids | array of string | No | v1's patient filter: only these patients' alerts, by Signals id. Repeat the parameter or separate with commas. Alerts only. |
status | ACTIVE, RESOLVED, OPEN, CLOSED | No | ACTIVE or RESOLVED for alerts; OPEN or CLOSED with episodes=true. |
codes | array of string | No | Restrict to these LOINC codes. On episodes it defaults to the tenant's feedCodes, every code when it lists none. Alerts have no default: absent, every alert, including those that carry no code. |
since | string | No | Alerts raised, or episodes whose sort time is, at or after this instant: opened by default, last fired with sort=lastFiringAt. |
until | string | No | Alerts raised before this instant. Alerts only. |
acknowledged | boolean | No | Filter on whether the episode, or the alert, has been acknowledged. |
sort | time-desc, time-asc, openedAt, lastFiringAt | No | On alerts, v1's order: time-desc (the default) or time-asc. On episodes, which time they are listed by, newest first; since and cursor use it too. openedAt (the default) never changes, so a walk of every page sees each episode once. lastFiringAt is the newest firing reading, or the opening for an episode that has none; an episode that fires mid-walk moves above the cursor. |
page | number | No | v1's 1-based page of limit alerts. A page may start at most 10000 rows in; walk further with cursor. Alerts only. |
limit | number | No | — |
cursor | string | No | — |
tags[key] | string | No | v1's tag filter: only patients whose tags.key equals one of the comma-separated values, or holds one in an array. Repeat with other keys to require them all. Keys are alphanumeric; tags.key= is accepted too. |
Responses
| Status | Meaning |
|---|---|
200 | A page of alerts, or of episodes, plus the cursor for the next one. |
400 | The query carries a raw #, or more than 200 parameters. |
401 | Your ovok access token, or your client id and secret, are missing or invalid. |
403 | ovok refused the call: you lack a capability this route needs, or your session has no project, or project names another project, or your access covers only some patients and the call names none. From Signals: Authenticated, but the client's role does not permit this, or it is not attached to the patient. Or: episodicAlerts is not enabled for this tenant, and episodes were requested. |
404 | A patient the call names is not one you can read. |
409 | Your project has no Signals tenant of its own (SIGNALS_TENANT_NOT_OWN), or it is moving to another one. |
422 | A patient id is not 1 to 64 letters, digits, ., _, ~ or -. More than 100 patients are named. From Signals: An alert filter was sent with episodes=true, episodes=true arrived without project, or the page starts too deep. |
429 | Too many requests. Retry after the seconds in Retry-After. |
500 | ovok hit an unexpected fault, such as your project having no Signals submitter. |
502 | Signals answered with something ovok couldn't use, or refused ovok's own credential. |
503 | Signals is unavailable. Retry after the seconds in Retry-After. |
504 | Signals did not answer in time. |
Example
curl --request GET 'https://api.sandbox.ovok.com/v1/signals/api/alert' \
--user "${OVOK_CLIENT_ID}:${OVOK_CLIENT_SECRET}"Last updated on