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}/dataFind 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
| Status | Meaning |
|---|---|
ok | The widget has figures. |
empty | The widget ran and found no cost for its range and filters. |
error | This widget's query failed. The other widgets still answer. error.code uses the API error codes. |
no_range | Neither the widget nor its canvas has a date range, so there is nothing to ask. |
text | A text panel. Its content is in text. |
unsupported | A 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 status | error.code | Meaning |
|---|---|---|
400 | INVALID_INPUT | An option is wrong, for example from without to. The message says which. |
401 | UNAUTHENTICATED | No key, or the key is wrong, expired, or revoked. |
403 | MISSING_PERMISSION, FORBIDDEN | The key doesn't have Canvas: view, or its creator is no longer a member. |
404 | NOT_FOUND | No canvas with that id, or the key's creator can't open it. |
500, 503 | INTERNAL_ERROR, DEPENDENCY_UNAVAILABLE | Something 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
todayin 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"andMISSING_PERMISSION.
Related
- Canvases
- API and API reference, for questions a canvas doesn't answer
- MCP tools, to ask an AI client about a canvas