Automating Snapshots


Create a Snapshot

Required API Permission: Create Snapshots

You can create snapshots with the CLI, Node.js API, HTTP Site API or GraphQL API.

1calibre site create-snapshot --site=<site> --ref=<ref>
1import { Snapshot } from 'calibre'
2
3await Snapshot.create({
4  site: '<site>',
5  ref: '<ref>'
6})
1curl -X POST -H "Accept: application/json" \
2https://calibreapp.com/api/sites/<site>/snapshots?secret=<secret>&ref=<ref>
Example Response
1✔ Snapshot created: 1588
1{
2  "iid": 1588,
3  "ref": null,
4  "htmlUrl": "https://calibreapp.com/my-org/my-site/snapshots/1589",
5  "createdAt": "2018-01-01T16:20:00Z"
6  }
1{
2  "id": 62,
3  "generated_at": "2019-07-18T09:50:47Z",
4  "organisation_id": "calibre",
5  "site_id": "calibre",
6  "primary_region_id": "NorthVirginia",
7  "ref": null,
8  "client": "api",
9  "status": null,
10  "html_url": "https://calibreapp.com/calibre/calibre/snapshots/62",
11  "url": "https://calibreapp.com/api/sites/calibre/snapshots/62.json",
12  "created_at": "2019-07-18T09:50:46.966Z",
13  "pages": [
14    {
15      "uuid": "xxx-123-456-789-xxx",
16      "name": "Home",
17      "status": "scheduled",
18      "endpoint": "https://calibreapp.com",
19      "canonical": true,
20      "profile": "MotoG4, 3G connection",
21      "metrics": [],
22      "budget_alerts": null,
23      "artifacts": { "filmstrip": { "thumbs": [], "video": "" }, "har": "" }
24    },
25    {
26      "uuid": "xxx-123-456-789-xxx",
27      "name": "Home",
28      "status": "scheduled",
29      "endpoint": "https://calibreapp.com",
30      "canonical": true,
31      "profile": "Chrome Desktop",
32      "metrics": [],
33      "budget_alerts": null,
34      "artifacts": { "filmstrip": { "thumbs": [], "video": "" }, "har": "" }
35    }
36  ]
37}
ParameterRequiredDescription
siteYesSite slug, found in site settings
refNoSets a reference to the snapshot

List Snapshots

Required API Permission: Read Sites

You can list Snapshots with the CLI, Node.js API, GraphQL API or by using the HTTP Site API.

1calibre site snapshots --site=<site> --count=<count> --cursor=<cursor>
1import { Snapshot } from 'calibre'
2
3await Snapshot.list({
4  site: '<site>',
5  count: <count>,
6  cursor: '<cursor>'
7})
1curl -X GET -H "Accept: application/json" \
2https://calibreapp.com/api/sites/<site>/snapshots?secret=<secret>
Example Response
15 snapshots
2ID | URL                                                | REF | CLIENT | STATUS
342 | https:/calibreapp.com/calibre/calibre/snapshots/42 |     | api    | Completed 9:00pm 3-Jul-2019
441 | https:/calibreapp.com/calibre/calibre/snapshots/41 |     | api    | Completed 10:00am 3-Jul-2019
540 | https:/calibreapp.com/calibre/calibre/snapshots/40 |     | api    | Completed 5:00pm 2-Jul-2019
639 | https:/calibreapp.com/calibre/calibre/snapshots/39 |     | api    | Completed 4:00pm 2-Jul-2019
738 | https:/calibreapp.com/calibre/calibre/snapshots/38 |     | api    | Completed 8:00pm 1-Jul-2019
8To see snapshots after 38, run: calibre site snapshots --site=calibre --cursor=MjU
1{
2  "snapshots": [
3    {
4      "iid": 42,
5      "htmlUrl": "https:/calibreapp.com/calibre/calibre/snapshots/42",
6      "ref": null,
7      "client": "api",
8      "createdAt": "2019-07-03T11:00:00Z",
9      "status": "completed"
10    },
11    {
12      "iid": 41,
13      "htmlUrl": "https:/calibreapp.com/calibre/calibre/snapshots/41",
14      "ref": null,
15      "client": "api",
16      "createdAt": "2019-07-03T00:00:00Z",
17      "status": "completed"
18    },
19    {
20      "iid": 40,
21      "htmlUrl": "https:/calibreapp.com/calibre/calibre/snapshots/40",
22      "ref": null,
23      "client": "api",
24      "createdAt": "2019-07-02T07:00:00Z",
25      "status": "completed"
26    },
27    {
28      "iid": 39,
29      "htmlUrl": "https:/calibreapp.com/calibre/calibre/snapshots/39",
30      "ref": null,
31      "client": "api",
32      "createdAt": "2019-07-02T06:00:00Z",
33      "status": "completed"
34    },
35    {
36      "iid": 38,
37      "htmlUrl": "https:/calibreapp.com/calibre/calibre/snapshots/38",
38      "ref": null,
39      "client": "api",
40      "createdAt": "2019-07-01T10:00:00Z",
41      "status": "completed"
42    }
43  ],
44  "pageInfo": {
45    "hasPreviousPage": false,
46    "hasNextPage": true,
47    "endCursor": "NQ",
48    "startCursor": "MQ"
49  }
50}
1[
2  {
3    "id": 60,
4    "generated_at": "2019-07-18T10:05:33Z",
5    "organisation_id": "calibre",
6    "site_id": "calibre",
7    "primary_region_id": "local",
8    "ref": null,
9    "client": null,
10    "status": "completed",
11    "html_url": "https:/calibreapp.com/calibre/calibre/snapshots/60",
12    "url": "https:/calibreapp.com/api/sites/calibre/snapshots/60.json",
13    "created_at": "2019-07-12T19:00:00.000Z"
14  },
15  {
16    "id": 59,
17    "generated_at": "2019-07-18T10:05:33Z",
18    "organisation_id": "calibre",
19    "site_id": "calibre",
20    "primary_region_id": "local",
21    "ref": null,
22    "client": null,
23    "status": "completed",
24    "html_url": "https:/calibreapp.com/calibre/calibre/snapshots/59",
25    "url": "https:/calibreapp.com/api/sites/calibre/snapshots/59.json",
26    "created_at": "2019-07-12T03:00:00.000Z"
27  },
28  {
29    "id": 58,
30    "generated_at": "2019-07-18T10:05:33Z",
31    "organisation_id": "calibre",
32    "site_id": "calibre",
33    "primary_region_id": "local",
34    "ref": null,
35    "client": null,
36    "status": "completed",
37    "html_url": "https:/calibreapp.com/calibre/calibre/snapshots/58",
38    "url": "https:/calibreapp.com/api/sites/calibre/snapshots/58.json",
39    "created_at": "2019-07-11T10:00:00.000Z"
40  }
41]
ParameterRequiredDescription
siteYesSite slug, found in site settings
countNoThe number of records to return, maximum: 500
cursorNoThe cursor to fetch records after

Snapshot Status

The status of the Snapshot will be one of:

  • scheduled: the Snapshot has been scheduled, no tests are running.
  • running: at least one test is running.
  • verifying: at least one test is being verified.
  • errored: all tests completed, and at least one test errored or failed.
  • completed: all tests completed successfully.

Download Snapshot artifacts

Required API Permission: Read Page Tests

For each Snapshot, Calibre stores the following information:

  • lighthouse.json
  • screenshots
  • video render
  • HAR file
  • all other metrics and data available through the interface

You can download Snapshot artifacts with the CLI. Files will be saved to snapshot-artifacts directory.

1calibre site download-snapshot-artifacts --site=<site> --id=<id>

Delete a Snapshot

Required API Permission: Delete Snapshots

You can delete a Snapshot with the CLI, Node.js API or GraphQL API.

1calibre site delete-snapshot --site=<site> --id-<id> --confirm
1import { Snapshot } from 'calibre'
2
3await Snapshot.destroy({
4  site: '<site>',
5  id: '<id>'
6})
Example Response
1✔ Snapshot deleted: 42
1{
2  "iid": 42
3}
ParameterRequiredDescription
siteYesSite slug, found in site settings
idYesThe id of the snapshot

Retrieve a Snapshot

See the Retrieving Metrics guide for more details.