olOpsLyft Docs

Canvas data

Get the live numbers on a canvas, widget by widget, exactly as the canvas shows them.

The canvas data API returns what a canvas shows right now: every widget's figures, computed the same way the canvas computes them. Use it to put a canvas's numbers in a spreadsheet, a BI tool, or a weekly report without rebuilding each widget's query yourself.

It's one GET request per canvas, and it returns JSON.

Endpoint

GET https://v2.opslyft.com/api/canvas/{canvasId}/data

Find the canvas id in the canvas's address. Open the canvas in OpsLyft and copy the part after /iris/c/:

https://v2.opslyft.com/multicloud/iris/c/8f1d2c3b-4a5e-4f60-9b7c-1d2e3f4a5b6c
                                         └──────────── canvas id ────────────┘

Authenticate

Send an access key as a bearer token, as for the API:

Authorization: Bearer olt_1a2b3c4d_…

The key needs Canvas: view to read the canvas and Cost: view to read its figures. Viewer has both.

Your first request

curl "https://v2.opslyft.com/api/canvas/$CANVAS_ID/data" \
  -H "Authorization: Bearer $OPSLYFT_KEY"

Options

Add these to the query string. All are optional.

Prop

Type

# September only, for two widgets
curl "https://v2.opslyft.com/api/canvas/$CANVAS_ID/data?from=2026-09-01&to=2026-09-30&widgets=w-spend,w-top-services" \
  -H "Authorization: Bearer $OPSLYFT_KEY"

Response

{
  "canvas": {
    "id": "8f1d2c3b-4a5e-4f60-9b7c-1d2e3f4a5b6c",
    "name": "Monthly cloud review",
    "updatedOn": "2026-10-28T09:12:44.000Z",
    "revision": 14,
    "incomplete": false,
    "dateRange": { "from": "2026-10-03", "to": "2026-11-01" }
  },
  "asOf": "2026-11-02T10:04:31.512Z",
  "today": "2026-11-02",
  "widgets": [
    {
      "id": "w-top-services",
      "title": "Top services",
      "form": "bar",
      "reader": "cost",
      "status": "ok",
      "range": { "from": "2026-10-03", "to": "2026-11-01" },
      "groupBy": ["service"],
      "currency": "USD",
      "total": 48210.37,
      "rowCount": 6,
      "rows": [
        { "service": "Amazon EC2", "cost": 21904.12 },
        { "service": "Amazon RDS", "cost": 8120.55 }
      ],
      "truncated": false,
      "warnings": [],
      "request": { "providers": ["aws"], "dateRange": { "from": "2026-10-03", "to": "2026-11-02" }, "groupBy": ["service"], "topN": 5 }
    },
    { "id": "w-notes", "title": null, "form": "text", "reader": "text", "status": "text", "text": "## Notes\nReviewed with finance on the 1st." }
  ]
}

Widgets come back in the order they sit on the canvas.

Each widget

Prop

Type

Statuses

StatusMeaning
okThe widget has figures.
emptyThe widget ran and found no cost for its range and filters.
errorThis widget's query failed. The other widgets still answer. error.code uses the API error codes.
no_rangeNeither the widget nor its canvas has a date range, so there is nothing to ask.
textA text panel. Its content is in text.
unsupportedA widget that shows forecasts, optimisation, inventory, or tickets. These come from their own pages and aren't returned yet.

How the figures are computed

The same way the canvas computes them, for each widget:

  • Date range. The widget's own range if it has one, otherwise the canvas's. Ranges such as Last 30 days end yesterday, as in the app.
  • Filters. The canvas's filters apply, unless the widget ignores them. A widget's filter on a dimension replaces the canvas's filter on that same dimension.
  • Cost type. The widget's own, otherwise each cloud's default from Settings → Cost defaults.
  • Rows. Charts return the rows they draw: their top 3 to 10, as set on the widget. Tables, heat maps, and world maps return every row, up to 20,000.

Figures read through the same cost engine as the app, so a widget's numbers match the canvas for the same day.

Which canvases a key can read

A key reads the canvases the person who created it can open: their own, and those shared with them, their teams, or the whole organisation.

The figures use the key's own access, which can be narrower. A key scoped to two AWS accounts returns those two accounts' cost, even on a canvas its creator sees in full.

Errors

An error comes back with an HTTP status and a body like this:

{ "error": { "code": "NOT_FOUND", "message": "No canvas with that id that you can see." } }
HTTP statuserror.codeMeaning
400INVALID_INPUTAn option is wrong, for example from without to. The message says which.
401UNAUTHENTICATEDNo key, or the key is wrong, expired, or revoked.
403MISSING_PERMISSION, FORBIDDENThe key doesn't have Canvas: view, or its creator is no longer a member.
404NOT_FOUNDNo canvas with that id, or the key's creator can't open it.
500, 503INTERNAL_ERROR, DEPENDENCY_UNAVAILABLESomething went wrong on OpsLyft's side. Retry.

A failed widget doesn't fail the request: it comes back with status: "error" and the rest of the canvas still answers.

Tips

  • Set a long timeout. A canvas reads its widgets a few at a time, so a large canvas over a long range can take a minute or more.
  • Ask for the widgets you need with widgets. It's faster than reading the whole canvas.
  • Pin today in scheduled jobs, so a run that starts just after midnight UTC reads the day you meant.
  • Give the key Cost: view. Without it, every cost widget comes back with status: "error" and MISSING_PERMISSION.

On this page