<!-- https://developers.silktide.com/v1/governance/reports/get-report-results | Governance / Reports -->

# Get what a report shows

`GET /v1/reports/{reportId}/results`

Returns what a report shows: the template it is built from, the template's widgets, and each widget's results under its `widgetId`. Lay the widgets out with the template's `rows` and each widget's `row`, `column` and `order`.

A live report is built when you ask, over the dates it covers counted back from now, as the user who created it. A snapshot returns what it held when it was made, and never changes.

## Each widget's results

What a widget sends depends on its `uiId`. Every widget sends the same title bar, `resultState` and display fields. A `Score` adds the score, a `Table` a page of `rows`, a `Chart` its `series`, and so on. Check `resultState` before you read them: anything other than `ok` means the widget has nothing to show, and says why.

Tables and charts also send settings for drawing them on Silktide's own screens, which this page does not list and which can change. For a table's rows in a stable shape, read the same data through [results](https://developers.silktide.com/v1/concepts/results.md) instead.

## A live report for another website

`POST /v1/reports/{reportId}/results` answers the same as `GET`, and takes options as a JSON body. Send `context` to build a live report for something else of the same `contextTypeId` without changing the report:

```json
{ "context": { "websiteId": 2, "sectionId": 0 } }
```

The shapes are in [Context](https://developers.silktide.com/v1/concepts/context.md). A `GET` can send it in the query string instead, as `context[websiteId]=2&context[sectionId]=0`. A context that names nothing the API key's user can see falls back to the whole account, so a website widget then shows a `Message` that no website is selected. A snapshot ignores `context`.

## Errors worth knowing

A live report is built with its creator's permissions. If its creator no longer exists, such as a user who has left the account, it cannot be built, and this answers `403` with `AccessDenied`. A snapshot is unaffected.

A snapshot whose results could not be built when it was made has none to return, and answers `404` with `NotFound`.

## Request

### Path parameters

- `reportId` (integer, required, at least 1): The report.

## Response

Status `200`.

- `report` (object, required): The report, as Get a report returns it.
  - `reportId` (integer, required, at least 1): The report.
  - `reportTemplateId` (string, required, 1 to 16 characters): The report template it is made from.
  - `reportScheduleId` (integer, required): The report schedule that made it. `0` when it was not made by a schedule.
  - `contextTypeId` (string, required): What kind of thing it covers, copied from its template: `website`, `websites`, `account` or `property`. One of: `website`, `websites`, `account`, `property`.
  - `name` (string, required, at least 1 characters): Its name.
  - `thumbnailUrl` (string, required): A small screenshot of it. Empty until one is made, a few minutes after a snapshot is created.
  - `startTime` (integer, required): For a snapshot, the start of the dates it covers. `0` for a live report.
  - `endTime` (integer, required): For a snapshot, the end of the dates it covers. `0` for a live report.
  - `durationInterval` (string, required): The unit of how far back it looks. One of: `day`, `week`, `month`, `year`.
  - `durationPeriod` (integer, required, 0 to 90): How many `durationInterval`s back it looks. `week` and `4` cover the last four weeks.
  - `created` (integer, required): When it was created.
  - `creatorAssigneeId` (string, required): The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself.
  - `context` (object or map of any JSON or empty list, required): What it covers, in the shape its `contextTypeId` takes: `{"websiteId": 3, "sectionId": 0}` for one website, `{"criteria": {...}}` for several. `[]` when it has none.
    - `websiteId` (integer, required, at least 1): The website.
    - `sectionId` (integer, required): One of its sections. `0` for the whole website.
  - `isLive` (boolean, required): `true` for a live report (a dashboard), which is built afresh each time it is read. `false` for a snapshot, built once when it is created.
  - `version` (integer, required, at least 1): The version of the format it is stored in, which Silktide uses to upgrade older reports. Nothing to act on.
- `reportId` (integer, required, at least 1): The report again.
- `reportTemplate` (object, required): The template the results were built from. For a snapshot, as it was when the snapshot was made.
  - `reportTemplateId` (string, required, 1 to 16 characters): The template's id, such as `broken-links`.
  - `name` (string, required, at least 1 characters): Its name, as Silktide shows it.
  - `description` (string, required, up to 255 characters): What it is for, as Silktide shows it. Can be empty.
  - `rows` (list of objects, required): Its layout, one entry per row of widgets, top to bottom.
    - `columns` (integer, required, at least 1): How many widgets sit side by side in this row.
  - `created` (integer, required): When it was created.
  - `creatorAssigneeId` (string, required): The assignee who created it: a user (`u:`), an API key (`a:`), or `system` for those Silktide made itself.
  - `contextTypeId` (string, required): What kind of thing a report made from it covers: `website`, `websites`, `account` or `property`. One of: `website`, `websites`, `account`, `property`.
  - `context` (object or map of any JSON or empty list, required): The context its author built it with in Silktide. Reports made from it do not take it: send each report's own `context`. `[]` when it has none.
    - `websiteId` (integer, required, at least 1): The website.
    - `sectionId` (integer, required): One of its sections. `0` for the whole website.
  - `isCustom` (boolean, required): `true` if someone in the account made it, `false` if it comes with Silktide.
  - `isDisabled` (boolean, required): `true` when Silktide has switched it off. Live reports made from it cannot be read until it is switched back on.
- `widgets` (list of objects, required): The template's widgets, with every option filled in.
  - `widgetId` (integer, required, at least 1): The widget. Its results are under this id in `results`.
  - `reportTemplateId` (string, required, 1 to 16 characters): The template the widget belongs to.
  - `widgetTypeId` (string, required): What kind of widget it is, such as `Website/Score/Score`.
  - `row` (integer, required): The row it is in, from `0`, as in the template's `rows`.
  - `column` (integer, required): The column it is in within its row, from `0`.
  - `order` (integer, required): Its place among widgets in the same row and column, from `0`.
  - `options` (map of any JSON, required): How the widget is set up, such as its `name` and which score it shows. Depends on `widgetTypeId`.
  - `contextTypeId` (string, required): The kind of context the widget is locked to. Empty when it uses the report's context.
  - `context` (map of any JSON or empty list, required): The context the widget is locked to. `[]` when it uses the report's context.
  - `filters` (map of any JSON or empty list, required): Filters the widget starts with, such as a table's sort. `[]` when it has none.
- `results` (map of objects or empty list, required): Each widget's results, by `widgetId`. `[]` when the template has no widgets.
- `time` (integer, required): When the results were built: now for a live report, when it was made for a snapshot.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 403 | `EditionNotAvailable` | The account does not have Silktide 4. Reports, report schedules and report templates are Silktide 4's, so an account with only Silktide 5 cannot use them. |
| 400 | `InvalidRequest` | `reportId` is not a whole number. `properties.field` is `reportId`. |
| 404 | `ModelNotFound` | No report with that id exists in the account. |
| 404 | `NotFound` | The report is a snapshot with no results, because they could not be built when it was made. |
| 403 | `AccessDenied` | The API key's user cannot see the report, or a live report cannot be built: its creator no longer exists, or Silktide has switched its template off. |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: Can see this dashboard / snapshot
- Plan feature: none
- Edition: Silktide 4 only
- Cost: free
- Stability: stable, since 1.0.0

## Example: A heading and a score

```bash
curl "https://api.eu.silktide.com/v1/reports/2/results" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "report": {
    "reportId": 2,
    "reportTemplateId": "accessibility-22",
    "reportScheduleId": 0,
    "contextTypeId": "website",
    "name": "Wine Barrel WCAG 2.2",
    "thumbnailUrl": "",
    "startTime": 0,
    "endTime": 0,
    "durationInterval": "week",
    "durationPeriod": 2,
    "created": 1792953607,
    "creatorAssigneeId": "u:eu-12",
    "context": {
      "websiteId": 3,
      "sectionId": 0
    },
    "isLive": true,
    "version": 3
  },
  "reportId": 2,
  "reportTemplate": {
    "reportTemplateId": "accessibility-22",
    "name": "WCAG 2.2 summary",
    "description": "Summarize WCAG 2.2 standards for a specific website or section.",
    "rows": [
      {
        "columns": 1
      },
      {
        "columns": 1
      }
    ],
    "created": 1704913002,
    "creatorAssigneeId": "u:eu-12",
    "contextTypeId": "website",
    "context": [],
    "isCustom": true,
    "isDisabled": false
  },
  "widgets": [
    {
      "widgetId": 28,
      "reportTemplateId": "accessibility-22",
      "widgetTypeId": "Website/Presentation/Heading",
      "row": 0,
      "column": 0,
      "order": 0,
      "options": {
        "name": "Heading",
        "text": "Accessibility scores",
        "level": "2",
        "showBackground": false,
        "hideContextLabels": true
      },
      "contextTypeId": "",
      "context": [],
      "filters": []
    },
    {
      "widgetId": 29,
      "reportTemplateId": "accessibility-22",
      "widgetTypeId": "Website/Score/Score",
      "row": 1,
      "column": 0,
      "order": 0,
      "options": {
        "name": "WCAG 2.2 score",
        "categoryId": "wcag-22",
        "helpText": null,
        "helpUrl": null,
        "hideContextLabels": true
      },
      "contextTypeId": "",
      "context": [],
      "filters": []
    }
  ],
  "results": {
    "28": {
      "uiId": "Heading",
      "resultState": "ok",
      "header": {
        "name": "Heading",
        "contextLabels": [],
        "value": null,
        "decimals": 0
      },
      "footer": {},
      "helpText": null,
      "helpUrl": null,
      "canAddToDashboard": true,
      "controls": [],
      "instruction": null,
      "buildDuration": 0.001,
      "isOutOfDate": false,
      "showBackground": false,
      "exportFormats": [],
      "text": "Accessibility scores",
      "level": 2
    },
    "29": {
      "uiId": "Score",
      "resultState": "ok",
      "header": {
        "name": "WCAG 2.2 score",
        "contextLabels": [],
        "value": null,
        "decimals": 0
      },
      "footer": {},
      "helpText": null,
      "helpUrl": null,
      "canAddToDashboard": true,
      "controls": [],
      "instruction": null,
      "buildDuration": 0.016,
      "isOutOfDate": false,
      "showBackground": true,
      "exportFormats": [
        "csv"
      ],
      "score": 20.2,
      "lastScore": null,
      "approved": null,
      "ignored": null,
      "fixed": null,
      "scoreOverTime": []
    }
  },
  "time": 1794235487
}
```