olOpsLyft Docs

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.

OperationWhat it returnsNeeds
myAccessWhat your key can doAny key
dimensionsWhat you can group and filter cost bycost.view
filters / filterValuePageThe values of a dimensioncost.view
costQueryCost, grouped, filtered, and over timecost.view
anomalyList / anomalyCost anomaliesmonitor.view
atlasInventory / atlasInventoryGroup / atlasResourceLive resourcesatlas.view
getBudgets / getBudgetById / budgetForecasts / budgetDailySpendBudgets and their forecastsbudget.view
tickets / ticketTickets for cost workticket.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

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_allocation above), 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.

On this page