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

# Anomalies

> Tools for what automated checks found in your network's tracking data: failing partner postbacks, partners going quiet, collapsing offer conversions, conversions over the cap and more.

> [!NOTE]
>
> **Beta.** The anomaly tools are in beta. Response fields, the list of anomaly types and finding ids may change as the checks evolve, and new anomaly types and fields will be added.

Anomalies are what automated checks found in your network's tracking data for the last complete day. Each check compares the last 7 days with the median of the 5 whole weeks before, so one unusual day does not raise a finding and a slow change is still caught.

| Tool | What it does | Requires |
| - | - | - |
| [get\_anomaly\_summary](#get_anomaly_summary) | Counts of the current findings by type, severity and reading, and the largest amounts | Reporting |
| [list\_anomalies](#list_anomalies) | A page of findings, worst first, with filters | Reporting |
| [get\_anomaly](#get_anomaly) | One finding with its full evidence | Reporting |

Call them in that order: the summary to see what exists, the list filtered to what the question is about, the detail for one finding. For a question about one partner or offer, skip the summary and call the list with that subject; never call the summary and the list at the same time, since each can start the day's computation. Then use the reporting tools to verify before acting: a finding is a lead from an automated check, not a conclusion.

> [!NOTE]
>
> **The first call of the day can take a moment.** Findings are computed when a network first asks for them each day, which usually takes a few seconds to 20 seconds and up to about a minute on the largest networks (set your client timeout above that), and then reused for the rest of the day. If the computation fails, every tool returns `"status": "failed"` with `retry_after_seconds`: call again after that wait. A failed result never means "no anomalies".

***

## Types

| `anomaly_type` | About | What it finds |
| - | - | - |
| `partner_postback_failing` | Partner | The share of postbacks the partner's server rejects jumped, or was already at least half in a normal week (`chronic`; `since_at_least` is where the data starts, not when the failures began). The evidence names the endpoint hosts, never the full URL |
| `partner_postback_no_click_id` | Partner | More postbacks than usual went out with an empty click id or an unfilled macro, so the partner cannot match them |
| `partner_into_full_caps` | Partner | Far more of the partner's clicks than usual are turned away because the offers they promote are capped |
| `partner_went_quiet` | Partner | The partner's revenue fell well below its normal week. `clicks_fell_too` says whether the partner sent less traffic (`true`) or the traffic stopped converting (`false`) |
| `partner_invalid_conversion_spike` | Partner | The share of the partner's conversions and events rejected on arrival jumped. `dominant_code` names the main reason |
| `offer_conversions_collapsed` | Offer | The offer's conversions collapsed while its clicks held, which usually means the advertiser's tracking broke or the network rejected them |
| `offer_over_cap` | Offer | Conversions arrived after the offer's cap was full. `chronic` marks demand that is above the cap in most weeks |
| `partner_offer_conversion_rate_drop` | Partner, on one offer | The partner's conversion rate on the offer fell far below its normal weeks, on enough traffic to be sure. `segment` names the offer. Medium severity |
| `partner_offer_conversion_rate_rise` | Partner, on one offer | The rate rose far above normal. Read `worth_a_look`: a better placement, or conversions that should be checked. Low severity, so listed only when asked for |

The revenue of `partner_went_quiet` and the conversions of `offer_conversions_collapsed` count only conversions that were not rejected, so a drop with clicks held can be conversions the network rejected rather than a tracking break. A performance report grouped by conversion error code tells the two apart. A `partner_went_quiet` finding does not say when the drop started: a performance report by day shows the stop date and any on and off rhythm.

An empty result means no check fired, not that the partner or offer is fine. The checks that compare with earlier weeks (went quiet, collapsed conversions, conversion rates, postbacks, rejected conversions) need activity in at least three of the five earlier weeks, so they cannot judge a newer partner or offer.

Rate findings group in one of two ways. Three or more partners moving the same way on one offer are one row, an offer-wide shift. Otherwise, three or more offers of one partner moving the same way are one row, a change in how that partner sends traffic. Drops and rises on one offer are separate rows, unless the offer has its own finding (over cap or conversions collapsed), which ties both to it. A partner's rate row never joins that partner's other findings.

**Severity** is `high`, `medium` or `low`. A low-severity finding is a clear change that is small for your network.

**Reading** says how to take a finding: `bad` (a problem) or `worth_a_look` (an ambiguous change worth a question). A `good` reading, for what is going well, is reserved for checks that are not available yet.

**Money** comes with an amount, a kind (`revenue_below_normal` or `revenue_turned_away`) and a currency. Amounts of different kinds or currencies are never added together.

***

## get\_anomaly\_summary

Counts of the network's current findings, and the findings carrying the most money.

**Requires:** Reporting (Read Only)

**Ask for it:** *"Is anything wrong in my network this week?"* · *"What should I look at today?"*

**Parameters:** none.

**Returns:** `status`; `report_date`; the dates of the current week and the baseline; `total`; `by_severity`, `by_reading` and `by_type`; `incidents_in_default_list` (the number of rows `list_anomalies` returns with no filters, since findings that share a cause are one row) and `incidents_total` (the same across every severity and reading); `skipped_for_short_history` (types not run because the network has less history than they need; a single new partner or offer is not listed there); `largest_amounts`; and `scope` when the caller sees only some partners. The counts include low-severity findings, which `list_anomalies` leaves out unless asked.

`largest_amounts` lists the findings carrying the most money, one group per currency and money kind (the network's currency first, and within a currency the group with the largest amount first), with at most 3 findings per group and at most one per incident, so it is a list of leads, not a total. Amounts are never added, and amounts in different currencies are never compared. Each entry has `finding_id`, `incident` (the `finding_id` of the incident's worst finding, which `get_anomaly` accepts; a filtered list may lead the row with another finding), `anomaly_type`, `severity`, `subject_type`, `subject_id`, `subject_name`, `offer_name` for a partner on one offer, `amount`, and `chronic` when set. Entries cover every severity: a low one comes back from `list_anomalies` only when `severity` includes `low`.

***

## list\_anomalies

A page of findings, ordered by reading (bad, then worth a look), then severity, then money within one currency. A filter replaces its default: `severity=low` returns only low findings, `severity=high|medium|low` returns all of them.

**Requires:** Reporting (Read Only)

**Ask for it:** *"Which partners went quiet this week?"* · *"Show me everything about offer 123."*

**Parameters**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `anomaly_type` | string | No | all | Types to keep, `\|`-separated (e.g. `partner_went_quiet\|offer_over_cap`) |
| `subject_type` | string | No | none | `affiliate` (a partner) or `offer`. Required with `subject_id` |
| `subject_id` | number | No | none | Only findings about this partner or offer; for an offer, also the partner findings about it (conversion rates judged on it, a partner gone quiet with most of its loss on it) |
| `reading` | string | No | `bad\|worth_a_look` | `bad`, `worth_a_look`, `\|`-separated |
| `severity` | string | No | `high\|medium` | `high`, `medium`, `low`, `\|`-separated |
| `page` | number | No | 1 | Page number |
| `page_size` | number | No | 20 | Rows (incidents) per page (1–50); a row can hold several findings, so page by `total_groups` |

**Returns:** `status`, `report_date`, `page`, `page_size`, `total_matching` (findings), `total_groups` (rows), and `findings`. Findings that share a cause come as one row: the worst finding, with the others under `related` (at most 20 per row; `related_omitted` counts the rest) and what ties them in `related_by` (`affiliate:<id>`, `offer:<id>`, `host:<endpoint>`, `offer_collapse:<id>` for a partner gone quiet on an offer whose conversions collapsed, `offer_rate_drop:<id>` / `offer_rate_rise:<id>` for partners' conversion rates moving on one offer, or `affiliate_rate_drop:<id>` / `affiliate_rate_rise:<id>` for one partner's conversion rate moving on several offers), with `partners` and `offers` counting what the row covers; for example a partner's postbacks failing and lacking a click id, or a partner gone quiet on an offer whose conversions collapsed. A row linked only through findings your filters leave out has `related_through` instead of `related_by`. Each related entry carries its own `metric_current`, `metric_baseline` and `money`. Rates are given to four significant digits, amounts to the cent. Each finding has `finding_id`, `anomaly_type`, `severity`, `reading`, `subject_type`, `subject_id`, `subject_name` (the partner's or offer's name; absent if it was deleted), `offer_name` for a partner on one offer, `metric_name`, `metric_current`, `metric_baseline`, `baseline_kind` and, where it applies, `money`. Evidence here carries only `chronic`, `since_at_least`, `clicks_fell_too` and `dominant_code` where the finding has them; `get_anomaly` returns all of it.

***

## get\_anomaly

One finding with its full evidence.

**Requires:** Reporting (Read Only)

**Parameters**

| Parameter | Type | Required | Default | Description |
| - | - | - | - | - |
| `finding_id` | string | Yes | none | The `finding_id` from `list_anomalies` |

**Returns:** `status`, `report_date`, the dates compared, and `finding`: its fields as in `list_anomalies`, with the full `evidence` (the counts behind it, such as the problem endpoint hosts for postbacks, every currency's figures for a partner that went quiet, or the rejected rows by error code), plus `related_finding_ids` and `related_by` when it belongs to an incident. A `finding_id` stays the same across calls and days while the same thing is wrong.

***

## Access and limits

* **Partner scope.** An employee or key limited to some partners sees only findings about those partners and no offer findings; the summary counts only what they can see and says so in `scope`. A finding outside that scope reads as not found.
* **No history.** There is no resolved or dismissed state: a finding that is gone today was not necessarily fixed.
* **Currencies.** Partners and offers are judged in each currency separately. A partner that went quiet is reported once, in the currency with its largest normal week, with every currency's figures in the evidence.
* **New networks.** A type that needs more history than the network has is skipped and listed in `skipped_for_short_history`.


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