Anomalies API V2 (Alpha)
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 and are including the following headers in every request:
x-finout-client-idx-finout-secret-keyYou are familiar with Query Language V2 fields (costCenter, key, type) — dimension values in the response follow this vocabulary.
Rate Limits
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
from
integer
Yes
Start of the detection time range, Unix timestamp in milliseconds.
Use from and to to retrieve anomalies detected within a specific time window
to
integer
Yes
End of the detection time range, Unix timestamp in milliseconds.
Maximum range: 7 days.
Use from and to to retrieve anomalies detected within a specific time window
type
enum[]
No
Filter by alert type.
Acceptable values: cost, usage, unitEconomics, financialPlanRunRate, or commitmentExpiration.
When omitted, all alert types are returned.
Example: ?type=cost&type=usage.
sortDirection
string
No
asc or desc.
Default: desc
pageSize
integer
No
Results per page.
Default 50, max 100.
cursor
string
No
Pagination cursor.
Use the nextCursor value from the previous response.
Example request
GET /alerts?from=1785542400000&to=1788134400000&type=cost&type=usage&sortDirection=desc&pageSize=50
Response
requestId
string
Unique identifier for the request.
pagination
object
Pagination metadata.
pagination.nextCursor
string
Cursor for the next page.
null when there are no more pages.
pagination.hasMore
boolean
Whether additional pages exist.
data
array<object>
Array of up to pageSize alert executions.
Alert fields shared by all types
Returns on every alert regardless of type.
data[].id
string
Unique alert execution ID.
data[].alertConfigurationID
string
ID of the alert configuration that produced this alert execution.
data[].name
string
Alert name.
data[].type
enum
Alert type: cost, usage, unitEconomics, financialPlanRunRate, or commitmentExpiration.
data[].detectionTime
integer
When the alert was detected, Unix timestamp in milliseconds.
data[].data
object
The details of the alert, based on its type. See the breakdowns below for cost, usage, unitEconomics, financialPlanRunRate, or commitmentExpiration.
Cost alert specific fields
data[].data.dimensions
array<object>
MegaBill dimensions the alert occurred on.
An empty array means all alerts (anomaly not tied to a specific dimension)
data[].data.dimensions[].costCenter
string
Cost center the dimension belongs to (e.g. AWS, virtual_tag).
data[].data.dimensions[].type
string
Key type of the dimension, e.g. billing_dimension or tag.
data[].data.dimensions[].key
string
Dimension's key name, e.g. service, region.
data[].data.dimensions[].value
string
Dimension's value for which the anomaly was detected, e.g. AmazonEC2.
data[].data.actualCost
number
Actual cost observed during the Evaluation Period.
data[].data.expectedCost
number
Expected cost, calculated from the Comparison Period.
data[].data.costType
string/null
Cost type the alert was evaluated on, e.g. netAmortizedCost.
data[].data.evaluation
object
The Evaluation and Comparison Period settings are used to detect this alert.
data[].data.evaluation.interval
string
Time interval the Evaluation and Comparison Periods are measured in, e.g. day, week
data[].data.evaluation.evaluationPeriod
integer
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.
data[].data.evaluation.comparisonPeriods
integer
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
Usage specific fields
data[].data.dimensions
array<object>
MegaBill dimension the alert occurred on.
Empty array = Total (alert not tied to a specific dimension).
data[].data.dimensions[].costCenter
string
Cost center the dimension belongs to (e.g. AWS, virtual_tag).
data[].data.dimensions[].type
string
Key type of the dimension, e.g. billing_dimension or tag.
data[].data.dimensions[].key
string
Dimension's key name, e.g. service, region.
data[].data.dimensions[].value
string
Dimension's value where the alert was detected, e.g. AmazonS3.
data[].data.actualUsage
number
Actual usage observed during the Evaluation Period.
data[].data.expectedUsage
number
Expected usage, calculated from the Comparison Period.
data[].data.units
object
Unit of measurement the usage was evaluated in.
data[].data.units.costCenter
string
Cost center the unit belongs to (e.g. AWS).
data[].data.units.name
string
Unit name, e.g. Requests, Tokens.
data[].data.evaluation
object
The Evaluation and Comparison Period settings used to detect this alert.
data[].data.evaluation.interval
string
Time interval the Evaluation and Comparison Periods are measured in, e.g. day, week
data[].data.evaluation.evaluationPeriod
integer
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.
data[].data.evaluation.comparisonPeriods
integer
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.
unitEconomics specific fields
data[].data.dimensions
array<object>
MegaBill dimension the alert occurred on. Empty array = Total (alert not tied to a specific dimension).
data[].data.dimensions[].costCenter
string
Cost center the dimension belongs to (e.g. AWS, virtual_tag).
data[].data.dimensions[].type
string
Key type of the dimension, e.g. billing_dimension or tag.
data[].data.dimensions[].key
string
Dimension's key name, e.g. service, region.
data[].data.dimensions[].value
string
Dimension's value where the alert was detected, e.g. AmazonRDS.
data[].data.actualUnitCost
number
Actual unit economics (cost ÷ telemetry) observed during the Evaluation Period.
data[].data.expectedUnitCost
number
Expected unit economics, calculated from the Comparison Period.
data[].data.actualCost
number
Actual total cost observed during the Evaluation Period.
data[].data.expectedCost
number
Expected total cost, calculated from the Comparison Period.
data[].data.actualTelemetry
number
Actual telemetry value (the unit economics denominator, e.g. active users) observed during the Evaluation Period.
data[].data.expectedTelemetry
number
Expected telemetry value, calculated from the Comparison Period.
data[].data.costType
string/null
Cost type the alert was evaluated on, e.g. netAmortizedCost.
data[].data.evaluation
object
The Evaluation and Comparison Period settings used to detect this alert.
data[].data.evaluation.interval
string
Time interval the Evaluation and Comparison Periods are measured in, e.g. day, week
data[].data.evaluation.evaluationPeriod
integer
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.
data[].data.evaluation.comparisonPeriods
integer
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
runRate specific fields
data[].data.dimensions
array<object>
MegaBill dimension(s) the alert occurred on. Can hold multiple entries — one per group-by selected in the Financial Plan.
data[].data.dimensions[].costCenter
string
Cost center the dimension belongs to (e.g. virtual_tag).
data[].data.dimensions[].types
string
Key type of the dimension, e.g. virtual_tag.
data[].data.dimensions[].key
string
Dimension's key name, e.g. Vendor.
data[].data.dimensions[].value
string
Dimension's value where the alert was detected, e.g. Oracle Cloud.
data[].data.monthToDateCost
integer | null
Actual cost accrued so far this month, up to the detection date.
data[].data.monthlyBudget
integer | null
Monthly budget defined in the Financial Plan. Returned as null if no budget is set for that Financial Plan.
data[].data.ProjectedEndOfMonthCost
integer | null
The projected total cost for the month — i.e. the run rate — calculated by extrapolating the last 30 days of spend through month end.
commitmentExpiration specific fields
data[].data.commitmentId
string
Unique identifier of the commitment plan, e.g. an AWS Savings Plan ARN.
data[].data.provider
string
Cloud provider the commitment belongs to, e.g. AWS, Azure.
data[].data.commitmentType
string
Type of commitment, e.g. savingsPlans, reservedInstances.
data[].data.expirationTime
integer
When the commitment expires, Unix timestamp in milliseconds.
Cost - Response Example
Usage - Response Example
Unit economics - Response Example
RunRate - Response Example
Commitment - Response Example
Error Handling
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
Good — that Finout API V2 page gives the exact template Maayan's used to elsewhere: bold question, line break, plain-prose answer. Here's a FAQ section for the Anomalies API V2 doc, pulling from what's already in the spec:
FAQs
Which alert types does this API return?
Cost, Usage, Unit Economics, Run Rate, and Commitment Expiration. 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.
Last updated
Was this helpful?