DevelopersReference
Sittings
One row per tour play, for a tour, in a day window.
Base URL https://api.showpilot.com/v1. Every call needs Authorization: Bearer <api key>; see Authentication.
A tour's sittings, newest first
GET /tours/{id}/sittings
Scope: sittings:read. Operation id: listTourSittings.
One row per play. The operator's own plays from the dashboard are excluded. from and to are inclusive UTC days on the sitting's start.
Parameters
| Name | In | Type | Meaning |
|---|---|---|---|
id | path | string | The tour's UUID or public id. |
limit | query | integer | Page size, 1 to 200. Default 50. |
cursor | query | string | The nextCursor from the previous page. Opaque; never build one. |
from | query | string (date) | First day of the range (UTC), YYYY-MM-DD. Default is 29 days before to. |
to | query | string (date) | Last day of the range (UTC), YYYY-MM-DD, inclusive. Default is today. The range is at most 366 days. |
Example request
curl "https://api.showpilot.com/v1/tours/t_9f3k2q/sittings?limit=50&from=2026-08-25&to=2026-09-23" \
-H "Authorization: Bearer $SHOWPILOT_API_KEY"Runs against your sandbox with a test key.
Response
One page of sittings.
| Field | Type | Always | Meaning |
|---|---|---|---|
items | array of Sitting | yes | |
nextCursor | NextCursor | yes |
Sitting
One play of a tour by one viewer.
| Field | Type | Always | Meaning |
|---|---|---|---|
id | string | yes | The view session id. |
tourId | string (uuid) | yes | |
visitorId | string or null | yes | |
email | string or null | yes | |
source | string or null | yes | Where it played: preview, lightbox, embed, share, chat or legacy. |
startedAt | string (date-time) | yes | |
endedAt | string (date-time) | yes | |
seconds | integer | yes | |
stepViews | integer | yes | Step views including revisits. |
stepsSeen | array of integer | yes | Distinct step indexes |
maxStep | integer | yes | Furthest step index reached; -1 when none. |
completed | boolean | yes | |
ctaClicks | integer | yes |
NextCursor
Pass as cursor for the next page; null on the last page.
Errors
| Status | When |
|---|---|
| 400 | A parameter is malformed, such as a cursor this API did not issue, a limit under 1, or an unknown status. Code invalid-request. |
| 401 | No key, or an unknown or revoked key. Code unauthorized. |
| 403 | A valid key without the operation's scope (code insufficient-scope), or a plan without API access (code plan-api-off). |
| 404 | No object with that id in this workspace. Code not-found. |
| 429 | The key's bucket is empty. Code rate-limited; wait the Retry-After seconds. |