Skip to content
Olivares AI docs

finops module route (requires finops:budget:read)

GET
/v1/m/finops/alerts
 
curl --request GET \
  --url https://example.com/v1/m/finops/alerts \
  --header 'Authorization: Bearer <token>'

Lists the budget alerts, optionally filtered by budget_id.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Header Parameters

Section titled “ Header Parameters ”
X-Olivares-Tenant
string format: uuid

Target tenant id; required when the principal can act in more than one tenant.

Query Parameters

Section titled “ Query Parameters ”
alert_id
string format: uuid

Optional UUID validated by the handler (400 if malformed). A reference grants no access; an authorized tenant with no matching row receives an empty list.

budget_id
string

Optional budget filter, combined with alert_id.

limit
integer

Page size; default 100, store maximum 1000.

cursor
string

Opaque continuation cursor from the preceding page.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Tenant-scoped financial evidence; legacy numeric fields are classified separately. Forecast is not certified.

Media type application/json
object
cursor
string
has_more
required
boolean
items
required
Array<object>
object
amount_evidence
required
object
cause
string
envelope
object
alert_id
required
string
amount
required
object
causes
Array<string>
class
required
string
Allowed values: exact lower_bound unknown
currency
required
string
value_micro_usd
required

Canonical integer micro-USD, without floating-point conversion.

string | null
/^(0|-?[1-9][0-9]*)$/
budget_id
required
string
components
required
object
cost
required
object
causes
Array<string>
pages_read
integer
rows_read
integer
state
required
string
Allowed values: known unknown nonnegative_unknown indeterminate
value_micro_usd
required

Canonical integer micro-USD, without floating-point conversion.

string | null
/^(0|-?[1-9][0-9]*)$/
dynamic_reservation
required
object
causes
Array<string>
pages_read
integer
rows_read
integer
state
required
string
Allowed values: known unknown nonnegative_unknown indeterminate
value_micro_usd
required

Canonical integer micro-USD, without floating-point conversion.

string | null
/^(0|-?[1-9][0-9]*)$/
static_reservation
required
object
causes
Array<string>
pages_read
integer
rows_read
integer
state
required
string
Allowed values: known unknown nonnegative_unknown indeterminate
value_micro_usd
required

Canonical integer micro-USD, without floating-point conversion.

string | null
/^(0|-?[1-9][0-9]*)$/
context
required
object
evaluated_at
required
string
provenance_filter
required
string
read_consistency
required
string
sample_occurred_at
required
string
scope_column
string
scope_resolved
required
boolean
scope_value
string
scope_values
Array<string>
>= 2 items unique items
window_bounds
required
string
window_end
string
window_start
string
decision
required
object
causes
Array<string>
legacy_threshold_pct
required
integer
result
required
string
Allowed values: proven not_reached unproven
target_denominator
required
string
target_micro_usd
string
target_numerator
required
string
threshold
required
string
digest_version
required
integer
Allowed value: 1
legacy
required
object
note
string
spend_micro_usd
required
integer format: int64
value_kind
required
string
Allowed values: exact lower_bound unavailable
policy
required
object
action
required
string
config_fault
string
currency
required
string
dimension
required
string
id
required
string
key
required
string
limit_micro_usd
required

Canonical integer micro-USD, without floating-point conversion.

string
/^(0|-?[1-9][0-9]*)$/
name
required
string
period
required
string
reserved_micro_usd
string
version
required
integer format: int64
schema_version
required
integer
Allowed value: 1
tenant_id
required
string
evidence_hash

Recorded digest; may be invalid when state=unknown. A digest alone establishes no financial claim.

string
state
required
string
Allowed values: valid unknown
budget_id
required
string
dimension
required
string
id
required
string
key
string
legacy_value_kind
required
string
Allowed values: exact lower_bound unavailable unverified
limit_micro_usd
required
integer format: int64
period
required
string
period_start
required
string
severity
required
string
spend_micro_usd
required
integer format: int64
threshold_pct
required
integer format: int64
triggered_at
required
string
Example 
{
  "items": [
    {
      "amount_evidence": {
        "envelope": {
          "amount": {
            "class": "exact"
          },
          "components": {
            "cost": {
              "state": "known"
            },
            "dynamic_reservation": {
              "state": "known"
            },
            "static_reservation": {
              "state": "known"
            }
          },
          "decision": {
            "result": "proven"
          },
          "digest_version": 1,
          "legacy": {
            "value_kind": "exact"
          },
          "schema_version": 1
        },
        "state": "valid"
      },
      "legacy_value_kind": "exact"
    }
  ]
}

400

Section titled “ 400 ”

Bad request

Media type application/json
object
Example generated 
{}

401

Section titled “ 401 ”

Unauthenticated

Media type application/json
object
Example generated 
{}

403

Section titled “ 403 ”

Forbidden

Media type application/json
object
Example generated 
{}

404

Section titled “ 404 ”

Not found

Media type application/json
object
Example generated 
{}

409

Section titled “ 409 ”

Conflict / setup required

Media type application/json
object
Example generated 
{}

429

Section titled “ 429 ”

Rate limited

Media type application/json
object
Example generated 
{}

500

Section titled “ 500 ”

Store or evaluation failure

Media type application/json
object
Example generated 
{}