EzyInsights Detections API

Overview

A detection is one of your items, a wire story or a photo, found in one publisher article, for one of your subscriptions. It says which item (source), which article and publisher (article), how strong the match is (strength), and when we first saw it (first_detected_at). A detection has a stable id and a version that goes up whenever something you can see in it changes, such as a new score or an earlier first detection. You read detections in two ways: everything first detected in a period (GET /v1/detections), or everything new and changed since your last call (GET /v1/detections/changes, the change stream). Data starts on the day each subscription's stream begins, which GET /v1/me gives as data_starts; nothing earlier is available.

All times are ISO 8601 in UTC with Z. A field a content type does not have is absent, not null (an image has no source.language); an unknown value is null. Every answer carries an X-Request-Id; quote it when you write to support.

Quickstart

1. Get a key. Keys are created in the EzyInsights app under Settings › API › Keys, by EzyInsights staff or by an administrator of your subscription. A key looks like ezy_live_k7f3m2x5a4bc_… and is shown once: keep it in your secret store, never in code.

2. Check it. GET /v1/me says who the key is, which subscriptions it reads, where each stream's data starts and what your limits are:

   curl -s https://api.ezyinsights.com/v1/me \
     -H "Authorization: Bearer $EZY_API_KEY"
   

3. Start the change stream from a time in the last 31 days with since:

   curl -s "https://api.ezyinsights.com/v1/detections/changes?since=2026-09-23T00:00:00Z&limit=1000" \
     -H "Authorization: Bearer $EZY_API_KEY"
   

4. Store next_cursor from every answer, together with the rows it brought, and pass it as cursor next time instead of since. While has_more is true, call again at once.

5. Poll hourly with the stored cursor. When nothing is new you get an empty page and the same cursor back.

6. Upsert by id, keeping the higher version. Delivery is at least once, so the same version can arrive twice, and an older version must never overwrite a newer one.

A complete loop in Python, standard library only (run it hourly, for example from cron):

import json, os, sqlite3, time, urllib.error, urllib.parse, urllib.request
from datetime import datetime, timedelta, timezone

API = "https://api.ezyinsights.com"
KEY = os.environ["EZY_API_KEY"]  # ezy_live_...; never in the code

db = sqlite3.connect("detections.db")
db.execute("CREATE TABLE IF NOT EXISTS detections (id TEXT PRIMARY KEY, version INTEGER, body TEXT)")
db.execute("CREATE TABLE IF NOT EXISTS state (name TEXT PRIMARY KEY, value TEXT)")

def get(path, params):
    url = API + path + "?" + urllib.parse.urlencode(params)
    request = urllib.request.Request(url, headers={"Authorization": "Bearer " + KEY})
    for attempt in range(6):
        try:
            with urllib.request.urlopen(request, timeout=60) as answer:
                return json.load(answer)
        except urllib.error.HTTPError as error:
            wait = int(error.headers.get("Retry-After") or 2 ** attempt)
            if error.code not in (429, 500, 503) or wait > 300:
                raise  # 429 daily_allowance waits until 00:00 UTC: stop and run again later
            time.sleep(wait)
    raise RuntimeError("the API kept failing; try again later")

row = db.execute("SELECT value FROM state WHERE name = 'cursor'").fetchone()
if row:
    params = {"cursor": row[0]}
else:  # the first run: start a day ago (at most 31 days)
    since = datetime.now(timezone.utc) - timedelta(days=1)
    params = {"since": since.strftime("%Y-%m-%dT%H:%M:%SZ")}

while True:
    page = get("/v1/detections/changes", {**params, "limit": 1000})
    for d in page["data"]:
        db.execute(
            "INSERT INTO detections VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET "
            "version = excluded.version, body = excluded.body WHERE excluded.version > detections.version",
            (d["id"], d["version"], json.dumps(d)),
        )
    db.execute("INSERT OR REPLACE INTO state VALUES ('cursor', ?)", (page["next_cursor"],))
    db.commit()  # the rows and the cursor together
    if not page["has_more"]:
        break
    params = {"cursor": page["next_cursor"]}

For history older than 31 days, make a full copy first (next section), then run this loop.

A full copy, gap-free

The change stream starts at most 31 days back. To hold everything since your data starts:

1. Read the first page of GET /v1/detections for the most recent month and keep its as_of.
2. Walk GET /v1/detections month by month back to data_starts (from GET /v1/me), following next_cursor until has_more is false in each month, and upsert every row by id, keeping the higher version.
3. Start the change stream with since set to that first as_of, and keep following it as in the quickstart.

Anything that changed during the walk, including a first detection moving into a month you had already read, or a late file, reaches the stream after that as_of, so the stream carries it. Use the server's as_of, not your own clock, and start the stream within 31 days of it.

Authentication and keys

Send the key, or an access token, in the Authorization header of every request:

Authorization: Bearer ezy_live_k7f3m2x5a4bc_…

• The format. ezy_live_, then the key id (12 characters), an underscore and the secret (52 characters), all lower-case letters a–z and digits 2–7. The key id names the key in /v1/me and the app; the secret is shown once, when the key is made, and we keep only a hash of it.
• Never in a query string. Keys and tokens are read from the Authorization header only; a key in the URL is ignored and the request is refused with 401.
• What a key reads. A key is made for some or all of its account's subscriptions and reads only those. No answer names or counts any other subscription; asking for one is 400 with the same words whether it exists or not, and a detection id outside the key's subscriptions is 404.
• Optional limits on a key. An expiry date, and a list of addresses (IPv4 or IPv6, single or CIDR) it may be used from; from any other address it is refused with 403.
• Rolling a key. In the app, Roll key makes a new key with the same name and scope and keeps the old one working for the overlap you choose (1 hour, 24 hours or 7 days), after which it expires by itself. Deploy the new key within the overlap. Cursors survive a roll.
• Revoking a key. Revoke key stops the key, and every token made from it, within a minute. It cannot be undone.

A revoked, expired or unknown key is 401 unauthorized; a key of a suspended account is 403 forbidden.

Tokens

If your client prefers OAuth 2.0, exchange a key for an access token with the client credentials grant, and send the token as Authorization: Bearer <token> like a key:

curl -s https://api.ezyinsights.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=k7f3m2x5a4bc \
  -d "client_secret=$EZY_API_SECRET"

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600,
  "scope": "detections:read reports:read exports:create" }

• Two ways to send the credentials: client_id (the key id) and client_secret (the secret) in the form body, or as HTTP Basic, Authorization: Basic base64(<key id>:<secret>); not both. As a convenience the whole key (ezy_live_…) is also accepted as client_secret when its id matches client_id.
• The body is application/x-www-form-urlencoded, at most 4 KiB, with no parameter given twice; grant_type must be client_credentials.
• Lifetime: one hour (expires_in: 3600). When a token expires, requests answer 401 ("the access token has expired"); request a new one. Tokens are not stored and cannot be revoked one by one: revoking the key stops its tokens within a minute.
• Scopes. Every key has detections:read, reports:read and exports:create. Ask for fewer with scope (space-separated, a subset of the key's); leave it out for all of them. On every request the token's scopes are intersected with the key's current ones.
• Limits: at most 10 token requests a minute per client id and per address. A token lasts an hour, so one request an hour is enough.

The change stream and its guarantees

GET /v1/detections/changes gives every new and changed detection in the order it reached us, each with event, created or updated.

• At least once. A detection version may be delivered more than once (after a retried file).
• Upsert by id; version never decreases for an id across the stream.
• last_scored_at in the stream is as of the version delivered. A re-scoring that changes nothing else does not create a new version, so GET /v1/detections/{id} may show a later last_scored_at.
• Order is ingest order, not detection time. Recovery files and re-scorings arrive when they arrive.
• first_detected_at can move earlier when an older evaluation of a match is processed after a newer one; that arrives as an updated event with a higher version.

How to read it:

• Start with since, a time at most 31 days ago and not in the future: the stream starts at the first change delivered at or after it. Afterwards, always pass the cursor from your last answer. One of the two is required, never both.
• The cursor is a position in the stream. It never expires, survives a key roll and is valid with any filter. Store it with the rows it brought.
• Pages. A page stops at limit rows (at most 1,000) or after 50 chunks of the stream (a chunk is one export file's changes for one subscription), whichever comes first. So a page can hold fewer rows than limit, even none, with has_more: true: call again with next_cursor until has_more is false, then poll later with the last cursor.
• An empty stream. When none of your streams holds anything at or after since, the answer is an empty page with has_more: false and a cursor at the end of the newest stream; poll from it. When you are caught up, the cursor you get back is the one you sent.
• Streams per request. Each subscription and content type is one stream, and one request reads at most 20. A key with more narrows each request with subscription_id and content_type, and keeps a cursor for each.
• Filters (next sections but one) are applied to each row. Changing them between calls is allowed, but rows an earlier filter skipped are not delivered again.

Detections in a period

GET /v1/detections?from=…&to=… gives the current state of every detection first detected in the period: for reports, checks and looking back.

• from and to are required. Each is a date (2026-09-23) or an ISO 8601 time with Z or an offset (2026-09-24T10:00:00Z). from is inclusive and to exclusive, except that a date-only to includes its whole day: from=2026-09-23&to=2026-09-23 is one day, and to=2026-09-30 includes the 30th. A to in the future is read as now.
• Time zones. A date is read in the request's time zone: time_zone if you give one (an IANA name such as Europe/Berlin), else the subscription's own time zone when the request resolves to exactly one subscription, else UTC. Days follow the zone's clock changes. Every answer echoes the resolved from and to (as UTC times) and time_zone.
• At most 31 days. 31 calendar days when from and to are both dates, so a whole month is always one request; otherwise 31 × 24 hours, plus one hour for a clock change, between the two times. Walk longer periods month by month.
• Not before data starts. from may not be earlier than the day records begin: the earliest data_starts (GET /v1/me) of the requested streams, that day's start in the request's time zone. The 400 names data_starts.
• Sorts. sort=-first_detected_at (the default, newest first) or sort=first_detected_at (oldest first); ties are broken by id.
• Paging. limit is up to 1,000 when the request covers one stream (one subscription and content type) and up to 200 when it covers more; at most 4 subscriptions per request. Follow next_cursor until it is null. has_more can be true with an empty next page.
• The query cursor refuses a changed request. It carries a hash of the period, the time zone, the sort, the subscriptions and content types, the filters and fields, so a walk cannot silently change its question halfway: a cursor sent with anything changed is 400 ("the period or filters changed; start again"). Only limit may change between pages.
• Wide requests. A request whose period and subscriptions reach more than 64 shards of our storage is 400 ("narrow the period or the subscriptions").
• No event. Detections here are states, not changes; event belongs to the change stream. The same holds for GET /v1/detections/{id}.

What you must know:

• The answer is the current state: a detection re-scored tomorrow shows tomorrow's values.
• A period that ended less than two days ago is still filling, and a walk through it is not a consistent snapshot: matches keep arriving for about a day and a half, and a detection's first detection can move earlier when an older evaluation arrives late, which can move it to a page already read. Newest-first (the default) keeps new arrivals ahead of the cursor. For a complete, updating copy, use the change stream.
• Detections exist from each subscription's data_starts (GET /v1/me).

Filters and fields

The detection endpoints GET /v1/detections and GET /v1/detections/changes take the same filters, all combinable. A repeatable filter also takes a comma-separated list (publisher_id=42,43 is publisher_id=42&publisher_id=43).

min_band for each content type. Text bands run off < low < medium < high < max (usage thresholds 25, 50, 75 and 95%); image bands run low < medium < high (score thresholds 30 and 60). The same word is the same step for both types, so min_band=medium keeps text medium, high and max and image medium and high; min_band=off keeps everything; and min_band=max keeps only text max and excludes every image. With band, off and max match no image.

fields returns only the fields you name, so a loader that needs eight columns does not download forty: fields=first_detected_at,strength,article.url,article.publisher. A path is a field of the schema or an object holding some (source, strength, article, article.publisher), which comes back whole. id and version always come back, the detection's order is kept, and a field the content type does not have stays absent. fields also works on GET /v1/detections/{id}. Every field is listed under Schemas, and machine-readably at GET /v1/schema/detection.

Strict parameters. On the detection endpoints, a parameter the endpoint does not know is 400, and so is an empty value or a single-valued parameter given twice; the detail names it. schema_version=v1 (the default and only version) is accepted by every detection endpoint and by /v1/schema/detection.

Limits and allowances

• 120 requests a minute per key. Answers to an accepted key or token carry RateLimit-Limit: 120 and RateLimit-Policy: 120;w=60. Over it, 429 with type rate_limited and Retry-After: 60. The limit is counted per Cloudflare location, best effort, so a client spread over several locations can exceed it; no remaining count is given.
• Unknown credentials are rate-limited. Requests with key ids we have not recently seen are limited per address (about 10 a minute); over that, 429 rate_limited.
• Tokens: 10 requests a minute per client id and per address.
• The daily row allowance. Each account may read a number of detection rows per UTC day: the rows returned by /v1/detections, /v1/detections/changes and /v1/detections/{id} count. /v1/me shows it as limits.daily_rows. By default it is the larger of 1,000,000 and three times the rows the account's subscriptions produced in the last 31 days, so a runaway client can re-read about a month three times a day before it stops. Ask us to raise it for a large backfill.
• Keys before accounts. When an account goes over, its keys are throttled, those that read the most first, until the rest fit, so a runaway test script does not stop your production loader. The whole account is throttled only when a single key (with the keys it was rolled from) is over on its own; rolling a key does not reset its count.
• Throttled: the detection endpoints answer 429 with type daily_allowance, the reset time (the next 00:00 UTC) in the detail, and Retry-After with the seconds until then. The cursor you hold stays valid and nothing is lost. /v1/me, /v1/schema/detection and /oauth/token keep working, and /v1/me shows limits.throttled (key or account) with throttled_until.
• "About". The allowance is counted from our request metering every five minutes, so it takes effect about 8 minutes after it is passed. At the fastest possible rate (10 keys × 120 requests × 1,000 rows a minute) an account can read up to about 10 million rows past it before it is throttled.

Errors

Every error except the token endpoint's is a problem document (RFC 9457), sent as application/problem+json:

{ "type": "https://api.ezyinsights.com/errors/invalid_request", "title": "Invalid request",
  "status": 400, "detail": "limit must be between 1 and 1000",
  "request_id": "0b6f1c9e-3a52-4d8e-9f0a-6c1d2e3f4a5b" }

The detail says what was wrong in plain English; request_id is the answer's X-Request-Id.

The token endpoint answers errors as RFC 6749 does, { "error", "error_description" }: 400 invalid_request (not a form, a parameter twice, credentials both in the body and as Basic, malformed Basic credentials), 400 unsupported_grant_type, 400 invalid_scope (a scope the key does not have) and 401 invalid_client (wrong credentials, or a key that may not be used; with WWW-Authenticate: Basic realm="ezy-data" when Basic was used). A body over 4 KiB (413), the rate limit (429) and service faults (500, 503) are problem documents as above.

Retry 429, 500 and 503 after a wait, doubling it each time; never retry 400, 401, 403 or 404 unchanged.

Where data starts and gaps

• data_starts. GET /v1/me gives, per subscription and content type, the time the stream's records begin: the later of the start (00:00 UTC) of its first day of data and the time the export itself began. null means the stream has no data yet. GET /v1/detections refuses a from before that day.
• data_gaps. Detections arrive in export files, one per 10-minute window. A window whose file never arrived, or could not be read, is invisible in the stream, so GET /v1/me lists, per content type, the windows of the last 90 days that are missing (not arrived a day after it was due; still looked for once a day, and filled if it comes), abandoned (missing for 30 days and no longer looked for) or failed (arrived but could not be read, until we reset it), newest first, at most 200 each. Use it to tell "no matches" from "no data" when you reconcile.
• as_of. Every detection answer carries as_of: the end of the newest finished export window, the earliest over the content types read. Everything up to it has been read; newer windows may still be arriving. It is null while an export has no finished window.
• GET /v1/health needs no key. It answers 200 with status: ok, and 503 with status: degraded while one of our alerts that needs someone is open (alerts.page_worthy above 0), with each export's newest_done. The one you will meet is ingest stalled: it opens when an export's newest finished window ended more than 45 minutes ago, checked every five minutes, so health turns 503 about 45 to 50 minutes after the last finished window. During a deliberate pause of ingest for maintenance (alerts.paused is 1) the windows' age is not judged, so a pause alone keeps health at 200; as_of shows how far the data reaches.

Support

Write to support@ezyinsights.com with the X-Request-Id of the answer you are asking about. Changes to the API are announced in the changelog.

Reference

Every endpoint, generated from openapi.yaml, the OpenAPI 3.1 description of this API.

Schemas