API reference
Every operation you can call with an access key, with its arguments, the fields it returns, and an example.
Each operation below lists the permission it needs, its arguments, and the fields you can ask for. Send every request to POST https://v2.opslyft.com/api/api with your key. See API for authentication and conventions.
| Operation | What it returns | Needs |
|---|---|---|
myAccess | What your key can do | Any key |
dimensions | What you can group and filter cost by | cost.view |
filters / filterValuePage | The values of a dimension | cost.view |
costQuery | Cost, grouped, filtered, and over time | cost.view |
anomalyList / anomaly | Cost anomalies | monitor.view |
atlasInventory / atlasInventoryGroup / atlasResource | Live resources | atlas.view |
getBudgets / getBudgetById / budgetForecasts / budgetDailySpend | Budgets and their forecasts | budget.view |
tickets / ticket | Tickets for cost work | ticket.view, and the Tickets module |
Your key
myAccess
What your key can do: the modules your organisation has turned on, the permissions the key holds, and its grants.
query {
myAccess {
customerId
modules
keys
grants { roleName scope expiresAt }
}
}Prop
Type
Cost
Cost works in three steps: find the dimensions you can use, look up the values you want to filter on, then run a cost query.
dimensions
What you can group and filter cost by, and which cost types each provider supports. It reads no data, so it's fast.
query {
dimensions(providers: ["aws", "azure"]) {
dimensions { key label providers kind cardinality }
costTypes { provider costTypes { costType supported reason } }
}
}Arguments: providers: [String!]!.
Returns a DimensionCatalog:
Prop
Type
Tags are dimensions too. Get the tag names with filters on the tagKeys dimension, then group or filter by tag:<name>, for example tag:team. See Dimensions for what each built-in dimension means.
Allocations from Dimension Studio can be used the same way: see Cost by an allocation.
filters
The values of one or more dimensions over a date range. Leave dimensions out to get every low-cardinality dimension at once.
query {
filters(
providers: ["aws"]
dateRange: { from: "2026-09-01", to: "2026-10-01" }
dimensions: ["service_name"]
search: "elastic"
) {
provider dimension values totalCount error
}
}Prop
Type
Returns one entry per provider and dimension: provider, dimension, values, totalCount, and error (set when that provider doesn't have the dimension; the others still answer).
filterValuePage
One page of values for one dimension on one provider, sorted by value. Use it for high-cardinality dimensions such as resource IDs.
Arguments: provider: String!, dimension: String!, dateRange: EngineDateRange!, search: String, pageNo: Int, pageSize: Int.
Returns: values: [String!]! and totalCount: Int!.
costQuery
Cost for any slice: grouped by up to several dimensions, filtered, as a total or over time, and compared with another period.
query Cost($req: CostQueryInput!) {
costQuery(request: $req) {
rows
total
meta {
pagination { totalCount nextCursor }
warnings
}
}
}Example: EC2 and RDS cost by account in September, top 10.
{
"req": {
"providers": ["aws"],
"dateRange": { "from": "2026-09-01", "to": "2026-10-01" },
"groupBy": ["sub_account_name"],
"filterSets": [
{ "filters": [
{ "key": "service_name", "op": "in", "values": ["EC2 - Instances", "Relational Database Service"] }
] }
],
"topN": 10
}
}Response:
{
"data": {
"costQuery": {
"rows": [
{ "sub_account_name": "prod-main", "cost": 31002.1 },
{ "sub_account_name": "data-platform", "cost": 9870.4 }
],
"total": { "cost": 48210.55 },
"meta": { "pagination": { "totalCount": 12, "nextCursor": null }, "warnings": [] }
}
}
}Filter values must match exactly what the bill says, including case. Look them up with filters first rather than guessing: service names, for example, are EC2 - Instances, not Amazon EC2.
Request
Prop
Type
A filter is { key, op, values }. op is in (the default), notIn, like, notLike, ilike (not case-sensitive), or notIlike. The like family takes one pattern with % wildcards, for example %ec2%.
costType values differ by provider: AWS has billed, amortized, and effective, for example. Ask dimensions for the list; an unsupported one is refused with INVALID_INPUT. Leave it out to use your organisation's default.
Response
Prop
Type
Paging and sorting
Pages hold 1,000 rows by default. To get the next page, send the same request with the nextCursor you were given as pagination.cursor. A null cursor means you have everything. Paging options go inside pagination, not at the top of the request.
{ "pagination": { "cursor": "eyJ…", "pageSize": 1000 } }Sort with pagination.sortKey (cost, or with compareRange: oldCost, variance, or percentOfChange) and sortDir (asc or desc). A cursor only works with the query it came from.
More examples
{
"req": {
"providers": ["aws"],
"dateRange": { "from": "2026-01-01", "to": "2026-11-01" },
"groupBy": ["service_name"],
"granularity": "month",
"topN": 10
}
}Each row has service_name, bucket (the first day of the month), and cost: the ten largest services, plus an Others row for the rest of each month. For cost per provider, group by provider; for one combined total, send several providers with no groupBy.
{
"req": {
"providers": ["aws"],
"dateRange": { "from": "2026-10-01", "to": "2026-11-01" },
"compareRange": { "from": "2026-09-01", "to": "2026-10-01" },
"groupBy": ["tag:team"],
"pagination": { "sortKey": "variance", "sortDir": "desc" }
}
}Each row has team, cost, and oldCost, biggest increase first. Spend without the tag comes back as Untagged. Use your own tag name: filters on tagKeys lists them.
{
"req": {
"providers": ["aws"],
"dateRange": { "from": "2026-09-01", "to": "2026-10-01" },
"groupBy": ["service_name"],
"filterSets": [{ "filters": [{ "key": "sub_account_name", "op": "notIn", "values": ["sandbox"] }] }]
}
}Cost by an allocation
An allocation built in Dimension Studio adds its own tags, such as a business unit, to every row of the bill. Group or filter by one as alloc:<allocation>:<tag>:
{
"req": {
"providers": ["aws"],
"dateRange": { "from": "2026-10-01", "to": "2026-11-01" },
"groupBy": ["alloc:bu_allocation:vt_bu", "sub_account_name"]
}
}Rows name the column after the tag (vt_bu here). Cost the allocation can't place comes back as its default value, usually Untagged.
- The names. In Dimension Studio, the allocation's ID is under its name on Cost in scope (
bu_allocationabove), and each tag's key is under the tag's name on Tag the rows (vt_bu). The API doesn't list them. - The key needs All spend. An allocation can split shared cost across accounts, so a key limited to some accounts is refused with
FORBIDDEN. - Only what has run. Results reflect the allocation's last run, so a change made in Dimension Studio shows up once it has run again.
Anomalies
anomalyList
Cost anomalies that were active in a date range, with their impact, state, and recent daily series.
query {
anomalyList(
range: { start: "2026-10-01", end: "2026-10-30" }
clouds: ["aws"]
queue: needs
) {
total
rows {
key service account cloud severity kind state
impactPerDay costToDate pctChange startedAt endedAt owner
currency { code }
}
}
}Prop
Type
Returns rows, total (anomalies in the range before your filters), and countsByQueue (how many are in each queue). Each row (AnomalyRow) includes:
Prop
Type
anomaly
One anomaly in full.
Arguments: key: String!.
Returns: row (as above), rca (the likely cause), explanation (why it was flagged, in plain words), activity, comments, and dimensions.
Atlas inventory
Atlas is your live inventory: what exists now, polled every few hours. Costs are per month, amortised.
Atlas filters use conditions { k, op, v }. Conditions in a list must all match; any list may match. k is one of Service, Provider, State, Account, Team, Region, Type, Signal, Age, Cost/mo, or Resource. op is is, is not, includes, >, <, or is empty.
{ "filters": [[
{ "k": "Signal", "op": "is", "v": ["Idle"] },
{ "k": "Cost/mo", "op": ">", "v": ["50"] }
]] }atlasInventory
Resources grouped by a field, with counts and cost per group, and the top resources in each.
query Inventory($filters: [[AtlasConditionInput!]!]) {
atlasInventory(filters: $filters, groupBy: "Service", rowsPerGroup: 5) {
currency
total
groups {
key label count cost hasMore
rows { id name service provider account region state team cost ageDays signals }
}
}
}Prop
Type
Returns: currency, total (matching resources), freshness (when the inventory was read), groups (each with key, label, count, cost, rows, and hasMore), and facets (the values each field can take).
Each resource (AtlasResource) has id, name, service, provider, type, account, accountId, region, team, state, ageDays, createdAt, cost (per month), and signals (such as Idle, Underused, Orphaned, Stopped, Untagged).
atlasInventoryGroup
The rest of one group, page by page. Use it when a group in atlasInventory has hasMore: true.
Arguments: the same filters, search, and groupBy, plus group: String! (the group's key), offset: Int, and limit: Int.
Returns: rows and hasMore.
atlasResource
Everything Atlas knows about one resource.
Arguments: id: ID! (from atlasInventory).
Returns an AtlasResourceDetail with the resource's identity and arn, its cost basis, owner attribution, utilization, recent activity, facts, and attributes.
Budgets
The auth argument
getBudgets and getBudgetById take a required auth argument from an older version of the API. It is ignored: your key in the header is what counts. Pass auth: { accessToken: "header" } as shown.
getBudgets
The budgets your key can see. Where budgets are set month by month, each month is its own budget, so expect one per account per month, including months ahead.
query {
getBudgets(auth: { accessToken: "header" }, page: 1, limit: 50) {
total_count
data {
budget_id budget_name budget budget_utilization periodicity
account_owner account_manager created_at
}
}
}Arguments: auth: MulticloudAuth!, page: Int (default 1), limit: Int (omit to get every budget).
Returns: total_count and data, a list of Budget:
Prop
Type
getBudgetById
One budget.
Arguments: auth: MulticloudAuth!, budget_id: ID!.
Returns: a Budget, as above.
budgetForecasts
This period's forecast for every budget your key can see.
query {
budgetForecasts {
budgetId status periodStart periodEnd dataDate
amount spent forecast pct breachDate sev driver
}
}Returns a list of BudgetForecast:
Prop
Type
budgetDailySpend
Daily spend by service for one budget this period.
Arguments: budgetId: ID!.
Returns: a list of { date, service, cost }.
Tickets
tickets
Tickets for cost work: optimisation findings, anomalies, and budgets turned into tasks. Only for organisations that use Tickets; otherwise it returns MODULE_NOT_ENABLED.
query {
tickets {
total
currency
tickets {
id ref title team owner priority state stateLabel
moneyAtStake moneyKind monthlyAtStake dueAt breached verified createdAt
}
}
}Arguments: filters: [[AtlasConditionInput!]!], the same condition format as Atlas.
Returns: total, currency, and tickets, each with:
Prop
Type
ticket
One ticket with its full history.
Arguments: id: ID!.
Returns a TicketDetail.
Not available with access keys yet
These parts of OpsLyft can't be used with an access key yet. They need a signed-in person:
- Canvases (settings and widgets), datasets, and saved Cost Explorer views. A canvas's figures are available with the canvas data API.
- Dimension Studio's rules. Cost grouped or filtered by an allocation does work: see Cost by an allocation.
- Changes: triaging anomalies, creating or editing budgets, and creating or moving tickets.
The MCP allocation tools can read and change Dimension Studio rules with an Admin key.