> For the complete documentation index, see [llms.txt](https://docs.finout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finout.io/api/finout-api/finout-api-v2/anomalies-api-v2.md).

# Anomalies API V2

The Anomalies API V2 lets you programmatically pull your triggered alerts — cost, usage, unit economics, run rate, and commitment expiration — into your own systems.

***

### Prerequisites

Before using the Anomalies API V2:

* You have[ generated a Finout API token](https://docs.finout.io/api/finout-api/generate-an-api-token) and are including the following headers in every request:
* `x-finout-client-id`
* `x-finout-secret-key`
* You are familiar with [Query Language V2 fields](/api/finout-api/finout-api-v2/query-language-api-v2.md) (costCenter, key, type) — dimension values in the response follow this vocabulary.

***

### Rate Limits

| Endpoint         | Rate Limit (per account, per route) |
| ---------------- | ----------------------------------- |
| `GET /v2/alerts` | 10 req / min                        |

***

### GET /alerts

Returns a list of triggered alerts for your account, sorted by detection time.

***

#### Request

`GET https://app.finout.io/v2/alerts`

**Query Parameters**

<table><thead><tr><th width="145.51953125">Field</th><th width="144.5234375">Type</th><th width="141.4453125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>from</code></td><td>integer</td><td>Yes</td><td><p>Start of the detection time range, Unix timestamp in milliseconds. </p><p></p><p>Use <code>from</code> and <code>to</code> to retrieve anomalies detected within a specific time window</p></td></tr><tr><td><code>to</code></td><td>integer</td><td>Yes</td><td><p>End of the detection time range, Unix timestamp in milliseconds. </p><p></p><p><strong>Maximum range: 7 days.</strong><br><br>Use <code>from</code> and <code>to</code> to retrieve anomalies detected within a specific time window</p></td></tr><tr><td><code>type</code></td><td>enum[]</td><td>No</td><td><p>Filter by alert type. </p><p>Acceptable values: <code>cost</code>, <code>usage</code>, <code>unitEconomics</code>, <code>financialPlanRunRate</code>, or <code>commitmentExpiration</code>.</p><p></p><p>When omitted, all alert types are returned.</p><p><br></p><p>Example: <code>?type=cost&#x26;type=usage.</code> </p></td></tr><tr><td><code>sortDirection</code></td><td>string</td><td>No</td><td><p><code>asc</code> or <code>desc</code>. </p><p>Default: <code>desc</code></p></td></tr><tr><td><code>pageSize</code></td><td>integer</td><td>No</td><td><p>Results per page. </p><p>Default 50, max 100.</p></td></tr><tr><td><code>cursor</code></td><td>string</td><td>No</td><td><p>Pagination cursor. </p><p>Use the nextCursor value from the previous response.</p></td></tr></tbody></table>

**Example request**

`GET /alerts?from=1785542400000&to=1788134400000&type=cost&type=usage&sortDirection=desc&pageSize=50`

***

#### Response

<table data-header-hidden><thead><tr><th width="326.703125">Field</th><th width="147.46875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>requestId</code></td><td>string</td><td>Unique identifier for the request.</td></tr><tr><td><code>pagination</code></td><td>object</td><td>Pagination metadata.</td></tr><tr><td><code>pagination.nextCursor</code></td><td>string</td><td><p>Cursor for the next page. </p><p>null when there are no more pages.</p></td></tr><tr><td><code>pagination.hasMore</code></td><td>boolean</td><td>Whether additional pages exist.</td></tr><tr><td><code>data</code></td><td>array&#x3C;object></td><td>Array of up to <code>pageSize</code> alert executions.</td></tr><tr><td><strong>Alert fields shared by all types</strong></td><td><br></td><td>Returns on every alert regardless of type.</td></tr><tr><td><code>data[].id</code></td><td>string</td><td>Unique alert execution ID.</td></tr><tr><td><code>data[].alertConfigurationID</code></td><td>string</td><td>ID of the alert configuration that produced this alert execution.</td></tr><tr><td><code>data[].name</code></td><td>string</td><td>Alert name.</td></tr><tr><td><code>data[].type</code></td><td>enum</td><td>Alert type: <code>cost</code>, <code>usage</code>, <code>unitEconomics</code>, <code>financialPlanRunRate</code>, or <code>commitmentExpiration</code>.</td></tr><tr><td><code>data[].detectionTime</code></td><td>integer</td><td>When the alert was detected, Unix timestamp in milliseconds.</td></tr><tr><td><code>data[].data</code></td><td>object</td><td>The details of the alert, based on its type. See the breakdowns below for <code>cost</code>, <code>usage</code>, <code>unitEconomics</code>, <code>financialPlanRunRate</code>, or <code>commitmentExpiration</code>.</td></tr><tr><td><strong>Cost alert specific fields</strong></td><td></td><td></td></tr><tr><td><code>data[].data.dimensions</code></td><td>array&#x3C;object></td><td><p>MegaBill dimensions the alert occurred on. </p><p>An empty array means all alerts (anomaly not tied to a specific dimension)</p></td></tr><tr><td><code>data[].data.dimensions[].costCenter</code></td><td>string</td><td>Cost center the dimension belongs to (e.g. <code>AWS</code>, <code>virtual_tag</code>).</td></tr><tr><td><code>data[].data.dimensions[].type</code></td><td>string</td><td>Key type of the dimension, e.g. <code>billing_dimension</code> or tag.</td></tr><tr><td><code>data[].data.dimensions[].key</code></td><td>string</td><td>Dimension's key name, e.g. <code>service</code>, <code>region</code>.</td></tr><tr><td><code>data[].data.dimensions[].value</code></td><td>string</td><td>Dimension's value for which the anomaly was detected, e.g. <code>AmazonEC2</code>.</td></tr><tr><td><code>data[].data.actualCost</code></td><td>number</td><td>Actual cost observed during the Evaluation Period.</td></tr><tr><td><code>data[].data.expectedCost</code></td><td>number</td><td>Expected cost, calculated from the Comparison Period.</td></tr><tr><td><code>data[].data.costType</code></td><td>string/null</td><td>Cost type the alert was evaluated on, e.g. <code>netAmortizedCost</code>.</td></tr><tr><td><code>data[].data.evaluation</code></td><td>object</td><td>The Evaluation and Comparison Period settings are used to detect this alert.</td></tr><tr><td><code>data[].data.evaluation.interval</code></td><td>string</td><td>Time interval the Evaluation and Comparison Periods are measured in, e.g. <code>day</code>, <code>week</code></td></tr><tr><td><code>data[].data.evaluation.evaluationPeriod</code></td><td>integer</td><td>The length of the Evaluation Period, measured in the interval unit — the recent window of cost data checked against the Comparison Period average E.g. 5 with interval: day means the alert was evaluated over the last 5 days.</td></tr><tr><td><code>data[].data.evaluation.comparisonPeriods</code></td><td>integer</td><td>Length of the Comparison Period — the preceding window used to calculate the expected cost. E.g. 20 with interval: day means the expected cost was calculated from the 20 days before the Evaluation Period</td></tr><tr><td><strong>Usage specific fields</strong></td><td></td><td></td></tr><tr><td><code>data[].data.dimensions</code></td><td>array&#x3C;object></td><td><p>MegaBill dimension the alert occurred on. </p><p>Empty array = Total (alert not tied to a specific dimension).</p></td></tr><tr><td><code>data[].data.dimensions[].costCenter</code></td><td>string</td><td>Cost center the dimension belongs to (e.g. <code>AWS</code>, <code>virtual_tag</code>).</td></tr><tr><td><code>data[].data.dimensions[].type</code></td><td>string</td><td>Key type of the dimension, e.g. <code>billing_dimension</code> or <code>tag</code>.</td></tr><tr><td><code>data[].data.dimensions[].key</code></td><td>string</td><td>Dimension's key name, e.g. <code>service</code>, <code>region</code>.</td></tr><tr><td><code>data[].data.dimensions[].value</code></td><td>string</td><td>Dimension's value where the alert was detected, e.g. <code>AmazonS3</code>.</td></tr><tr><td><code>data[].data.actualUsage</code></td><td>number</td><td>Actual usage observed during the Evaluation Period.</td></tr><tr><td><code>data[].data.expectedUsage</code></td><td>number</td><td>Expected usage, calculated from the Comparison Period.</td></tr><tr><td><code>data[].data.units</code></td><td>object</td><td>Unit of measurement the usage was evaluated in.</td></tr><tr><td><code>data[].data.units.costCenter</code></td><td>string</td><td>Cost center the unit belongs to (e.g. <code>AWS</code>).</td></tr><tr><td><code>data[].data.units.name</code></td><td>string</td><td>Unit name, e.g. <code>Requests</code>, <code>Tokens</code>.</td></tr><tr><td><code>data[].data.evaluation</code></td><td>object</td><td>The Evaluation and Comparison Period settings used to detect this alert.</td></tr><tr><td><code>data[].data.evaluation.interval</code></td><td>string</td><td>Time interval the Evaluation and Comparison Periods are measured in, e.g. <code>day</code>, <code>week</code></td></tr><tr><td><code>data[].data.evaluation.evaluationPeriod</code></td><td>integer</td><td>The length of the Evaluation Period, measured in the interval unit — the recent window of cost data checked against the Comparison Period average E.g. 5 with interval: day means the alert was evaluated over the last 5 days.</td></tr><tr><td><code>data[].data.evaluation.comparisonPeriods</code></td><td>integer</td><td>Length of the Comparison Period — the preceding window used to calculate the expected cost. E.g. 20 with interval: day means the expected cost was calculated from the 20 days before the Evaluation Period.</td></tr><tr><td><strong>unitEconomics</strong> specific fields</td><td></td><td></td></tr><tr><td><code>data[].data.dimensions</code></td><td>array&#x3C;object></td><td>MegaBill dimension the alert occurred on. Empty array = Total (alert not tied to a specific dimension).</td></tr><tr><td><code>data[].data.dimensions[].costCenter</code></td><td>string</td><td>Cost center the dimension belongs to (e.g. <code>AWS</code>, <code>virtual_tag</code>).</td></tr><tr><td><code>data[].data.dimensions[].type</code></td><td>string</td><td>Key type of the dimension, e.g. <code>billing_dimension</code> or tag.</td></tr><tr><td><code>data[].data.dimensions[].key</code></td><td>string</td><td>Dimension's key name, e.g. <code>service</code>, <code>region</code>.</td></tr><tr><td><code>data[].data.dimensions[].value</code></td><td>string</td><td>Dimension's value where the alert was detected, e.g. <code>AmazonRDS</code>.</td></tr><tr><td><code>data[].data.actualUnitCost</code></td><td>number</td><td>Actual unit economics (cost ÷ telemetry) observed during the Evaluation Period.</td></tr><tr><td><code>data[].data.expectedUnitCost</code></td><td>number</td><td>Expected unit economics, calculated from the Comparison Period.</td></tr><tr><td><code>data[].data.actualCost</code></td><td>number</td><td>Actual total cost observed during the Evaluation Period.</td></tr><tr><td><code>data[].data.expectedCost</code></td><td>number</td><td>Expected total cost, calculated from the Comparison Period.</td></tr><tr><td><code>data[].data.actualTelemetry</code></td><td>number</td><td>Actual telemetry value (the unit economics denominator, e.g. active users) observed during the Evaluation Period.</td></tr><tr><td><code>data[].data.expectedTelemetry</code></td><td>number</td><td>Expected telemetry value, calculated from the Comparison Period.</td></tr><tr><td><code>data[].data.costType</code></td><td>string/null</td><td>Cost type the alert was evaluated on, e.g. <code>netAmortizedCost</code>.</td></tr><tr><td><code>data[].data.evaluation</code></td><td>object</td><td>The Evaluation and Comparison Period settings used to detect this alert.</td></tr><tr><td><code>data[].data.evaluation.interval</code></td><td>string</td><td>Time interval the Evaluation and Comparison Periods are measured in, e.g. <code>day</code>, <code>week</code></td></tr><tr><td><code>data[].data.evaluation.evaluationPeriod</code></td><td>integer</td><td>The length of the Evaluation Period, measured in the interval unit — the recent window of cost data checked against the Comparison Period average E.g. 5 with interval: day means the alert was evaluated over the last 5 days.</td></tr><tr><td><code>data[].data.evaluation.comparisonPeriods</code></td><td>integer</td><td>Length of the Comparison Period — the preceding window used to calculate the expected cost. E.g. 20 with interval: day means the expected cost was calculated from the 20 days before the Evaluation Period</td></tr><tr><td><strong>runRate specific fields</strong></td><td></td><td></td></tr><tr><td><code>data[].data.dimensions</code></td><td>array&#x3C;object></td><td>MegaBill dimension(s) the alert occurred on. Can hold multiple entries — one per group-by selected in the Financial Plan.</td></tr><tr><td><code>data[].data.dimensions[].costCenter</code></td><td>string</td><td>Cost center the dimension belongs to (e.g. <code>virtual_tag</code>).</td></tr><tr><td><code>data[].data.dimensions[].types</code></td><td>string</td><td>Key type of the dimension, e.g. <code>virtual_tag</code>.</td></tr><tr><td><code>data[].data.dimensions[].key</code></td><td>string</td><td>Dimension's key name, e.g. <code>Vendor</code>.</td></tr><tr><td><code>data[].data.dimensions[].value</code></td><td>string</td><td>Dimension's value where the alert was detected, e.g. <code>Oracle Cloud</code>.</td></tr><tr><td><code>data[].data.monthToDateCost</code></td><td>integer | null</td><td>Actual cost accrued so far this month, up to the detection date.</td></tr><tr><td><code>data[].data.monthlyBudget</code></td><td>integer | null</td><td>Monthly budget defined in the Financial Plan. Returned as null if no budget is set for that Financial Plan.</td></tr><tr><td><code>data[].data.ProjectedEndOfMonthCost</code></td><td>integer | null</td><td>The projected total cost for the month — i.e. the run rate — calculated by extrapolating the last 30 days of spend through month end.</td></tr><tr><td><strong>commitmentExpiration specific fields</strong></td><td></td><td></td></tr><tr><td><code>data[].data.commitmentId</code></td><td>string</td><td>Unique identifier of the commitment plan, e.g. an <code>AWS</code> <code>Savings Plan ARN</code>.</td></tr><tr><td><code>data[].data.commitmentName</code></td><td>string</td><td>Display name of the commitment plan, as shown in<a href="https://docs.finout.io/user-guide/optimize/my-commitments"> My Commitments</a>.</td></tr><tr><td><code>data[].data.provider</code></td><td>string</td><td>Cloud provider the commitment belongs to, e.g. <code>AWS</code>, <code>Azure</code>.</td></tr><tr><td><code>data[].data.commitmentType</code></td><td>string</td><td>Type of commitment, e.g. <code>savingsPlans</code>, <code>reservedInstances</code>.</td></tr><tr><td><code>data[].data.expirationTime</code></td><td>integer</td><td>When the commitment expires, Unix timestamp in milliseconds.</td></tr></tbody></table>

**Cost - Response Example**

```
      {
      "id": "cb5sag4ab-7cb4-4c1j-819e-c0b086e007eba",
      "alertConfigurationId": "4012a50fs-c0c0-4602-b8c2-05eb8cd9f91k",
      "name": "AWS: Sub Service",
      "type": "cost",
      "detectionTime": 1788134400000,
      "data": {
        "dimensions": [
          {
            "costCenter": "AWS",
            "type": "billing_dimension",
            "key": "cloud_service",
            "value": "EC2 - Compute"
          }
        ],
        "actualCost": 683.6796682759,
        "expectedCost": 403.6705176872,
        "costType": "amortizedCost",
        "evaluation": {
          "interval": "day",
          "evaluationPeriod": 1,
          "comparisonPeriods": 6
        }
      }
    }
```

**Usage - Response Example**

```
{
      "id": "c35a012z-fbqf-47a3-9451-e2e79c956281",
      "alertConfigurationId": "5cd19gbd-8cf0-4x62-8d44-b35845ab3f29",
      "name": "Anthropic Usage",
      "type": "usage",
      "detectionTime": 1788048000000,
      "data": {
        "dimensions": [
        ],
        "actualUsage": 15950497,
        "expectedUsage": 3389425.67665,
        "units": {
          "costCenter": "Anthropic",
          "name": "Tokens"
        },
        "evaluation": {
          "interval": "day",
          "evaluationPeriod": 1,
          "comparisonPeriods": 6
        }
      }
    }
```

**Unit economics - Response Example**

```
 {
      "id": "ceab3e2e-7da4-481a-18es-8415af794356",
      "alertConfigurationId": "00bc0a4e-4853-4814-b67c-0bca9b50f20f",
      "name": "K8s Namespaces",
      "type": "unitEconomics",
      "detectionTime": 1772841600000,
      "data": {
        "dimensions": [
          {
            "costCenter": "Kubernetes",
            "type": "kubernetes_resource",
            "key": "k8s_namespace",
            "value": "idle"
          }
        ],
        "actualUnitCost": 3704.1213335966,
        "expectedUnitCost": 1702.15593496,
        "actualCost": 467.40555752898,
        "expectedCost": 738.71585761465,
        "actualTelemetry": 0.5292573751583,
        "expectedTelemetry": 0.908867827323,
        "costType": "amortizedCost",
        "evaluation": {
          "interval": "day",
          "evaluationPeriod": 3,
          "comparisonPeriods": 2
        }
      }
    }
```

**RunRate - Response Example**

```
 {
      "id": "d6eba08-bs53-4b4a-852w-f4d51efade38",
      "alertConfigurationId": "b28a5ef8-a9b5-4a7c-9wa6-ca0976e9a395",
      "name": "The monthly run rate exceeded the budget in Financial Plan: DevOps Team FY 27",
      "type": "runRate",
      "detectionTime": 1787443200000,
      "data": {
        "dimensions": [
          {
            "costCenter": "AWS",
            "type": "billing_dimension",
            "key": "parent_cloud_service",
            "value": "AmazonEKS"
          }
        ],
        "monthToDateCost": 573.223543592,
        "projectedMonthEndCost": 789.9099749,
        "monthlyBudget": 600
      }
```

**Commitment - Response Example**

```
     {
      "id": "93a2a114-612f-4d74-9560-812b6b413a42",
      "alertConfigurationId": "ec8d97c9-e192-42d5-9db0-35921aecf02d",
      "name": "Reserved Instances EC2",
      "type": "commitmentExpiration",
      "detectionTime": 1778630400000,
      "data": {
        "commitmentId": "a758b004-2c28-4643-8ea9-aed4fac153d2",
        "commitmentName": "arn:aws:ec2:us-east-1:287411437194:reserved-instances/a758b004-2c28-4643-8ea9-aed4fac153d2",
        "provider": "AWS",
        "commitmentType": "reservedInstances",
        "expirationTime": 1780237419000
      }
    }
```

***

#### Error Handling&#x20;

| Code                       | Description                                                    | HTTP Status Code |
| -------------------------- | -------------------------------------------------------------- | ---------------- |
| `INVALID_TIME_RANGE`       | from >= to.                                                    | 400              |
| `TIMEFRAME_LIMIT_EXCEEDED` | Time range too large. Maximum allowed is 7 days.               | 400              |
| `VALIDATION_ERROR`         | Request failed general validation (e.g. malformed type value). | 400              |

***

### FAQs

**Which alert types does this API return?**\
[Cost](/user-guide/optimize/anomalies.md#h_5bb724f4af-1), [Usage](/user-guide/optimize/anomalies.md#usage-anomaly-beta), [Unit Economics](/user-guide/optimize/anomalies.md#unit-economics-anomaly), [Run Rate](https://docs.finout.io/api/finout-api/finout-api-v2/pages/5PznMwo0GOQ8YcSZGz74#id-5.-run-rate-alerts), and [Commitment Expiration](/user-guide/optimize/anomalies.md#h_3524f0f26d). Use the `type` query parameter to filter to one or more of these; omit it to get all types.

**What can I filter the response by?**\
`from`/`to` (detection time range, max 7 days), and `type` (alert type).

**Why is `dimensions` an empty array on some alerts?**\
An empty array means the alert applies to your Total cost or usage and isn't tied to a specific MegaBill dimension, rather than the field being missing.

**Why are some fields returned as `null` instead of a number?**\
When a value can't be legitimately calculated — for example `monthlyBudget` when no budget is set in the Financial Plan — the API returns `null` rather than a fabricated number.

**How do I page through results?**\
Use `pageSize` (default 50, max 100) and `cursor`. Pass the `nextCursor` from the previous response to get the next page; `hasMore` tells you when you've reached the end.

**What's the rate limit?**\
10 requests/minute per account on `GET /v2/alerts`.

**What's the maximum time range I can query?**\
7 days between `from` and `to`. Querying a longer range returns `TIMEFRAME_LIMIT_EXCEEDED`.

**Does the response payload look the same for every alert type?**\
The top-level fields (`id`, `alertConfigurationID`, `name`, `type`, `detectionTime`) are shared across all alerts, but the `data` object is type-specific

**What happens if I exceed the rate limit?**\
Requests beyond 10 req/min on `GET /v2/alerts` are rejected with a 400 error code.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.finout.io/api/finout-api/finout-api-v2/anomalies-api-v2.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.