Sessions Reference
The Sessions API provides insights into user interactions with your content, tracking reading sessions and engagement metrics. This feature allows you to retrieve detailed session data, including reading duration and page changes. This section will help you understand how to leverage session data to enhance user experience and content strategy.
warning
Not available by default in all plans. Contact [email protected] for more information about this endpoint.
info
Make sure you generated the api_token on your store. More info HERE
Retrieve
GET /integration-api/v1/consumption/sessions
Query Parameters
| Parameter | Type | Example |
|---|---|---|
cursor | string | /integration-api/v1/consumption/sessions?cursor=eyJzdGF....J1ZX0 |
issue_id | integer | /integration-api/v1/consumption/sessions?issue_id=1125899910000160 |
user_id | integer | /integration-api/v1/consumption/sessions?user_id=1125899911002602 |
reason_type | string | /integration-api/v1/consumption/sessions?reason_type=free_issue |
reason_value | integer | /integration-api/v1/consumption/sessions?reason_type=subscription_with_collectionsreason_value=3357 |
from_date | string | /integration-api/v1/consumption/sessions?from_date=2022-09-21&to_date=2022-09-23 |
to_date | string | /integration-api/v1/consumption/sessions?to_date=2022-09-23&to_date=2022-09-23 |
tip
Query parameters can be combined to achieve more specific filtering. All are optional, except the from_date and to_date fields which always go together, just as to send a reason_value you must specify reason_type.
tip
The cursor parameter can be used to paginate results.
Response
| Code | Description |
|---|---|
200 | Success |
403 | Feature disabled for your store |
401 | Unauthenticated |
{
"CODE": "success",
"current_page": 1,
"data": [
{
"uuid": "151:8000005:9000886:1734446548",
"issue_id": 8000005,
"issue_external_id": "9781234567890",
"user_id": 9000886,
"user_email": "[email protected]",
"user_name": "Maria Silva",
"user_external_id": "EXT-12345",
"client_type": "browser",
"device_os": "iOS",
"access_mode": "online",
"reason_type": "assigned_issue",
"reason_value": null,
"started_at": "2024-12-17 14:42:28",
"processed_at": "2024-12-17 14:42:28",
"last_heartbeat_at": null,
"seconds_reading": 125,
"page_changes": 12,
"page_views": 8,
"printed_pages": 2,
"notes": 1,
"highlights": 3,
"bookmarks": 0,
"resolved_captchas": 1
}
],
"path": "https://example.publica.la/integration-api/v1/consumption/sessions",
"per_page": 25,
"next_cursor": "eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"next_page_url": "https://example.publica.la/integration-api/v1/consumption/sessions?cursor=eyJzdGFydGVkX2F0IjoiMjAyNC0wOS0xOCAxNjoxMzoxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null,
"prev_page_url": null
}
The response is paginated with up to 25 sessions per page. Each session includes the following fields:
| Field | Type | Description |
|---|---|---|
uuid | string | Unique identifier for the session, combining tenant_id, issue_id, user_id, and timestamp. |
issue_id | integer | ID of the edition associated with the session. |
issue_external_id | string/null | External identifier of the edition, typically the ISBN. Null when the edition has no primary identifier. |
user_id | integer/null | ID of the user in the system. Null for guest sessions. |
user_email | string/null | Email of the user. Null for guest sessions. |
user_name | string/null | Name of the user. Null for guest sessions. |
user_external_id | string/null | External identifier of the user, set through integrations (e.g. SSO/LTI). Null when not provided. |
client_type | string | Platform where the session occurred. Possible values: app, browser. |
device_os | string | Operating system the session started from. Possible values: iOS, Android, Windows, Mac, Linux, Unknown. |
access_mode | string | How the content was accessed. online when the session was processed as it occurred; offline when read from downloaded content and synced later. |
reason_type | string | Reason the user accessed the content. Possible values are detailed below. |
reason_value | integer/null | Additional data related to the reason, such as the subscription plan ID for certain types. |
started_at | datetime | Timestamp when the session started (client occurrence time). |
processed_at | datetime/null | Timestamp when the session was processed by the platform (server ingestion time). Null for sessions recorded before this field was introduced. |
last_heartbeat_at | datetime/null | Timestamp of the last activity ping in the session. |
seconds_reading | integer | Duration of the session in seconds. |
page_changes | integer | Number of page changes during the session. |
page_views | integer | Number of page views recorded during the session. |
printed_pages | integer | Number of pages printed during the session. |
notes | integer | Number of notes created during the session. |
highlights | integer | Number of highlights created during the session. |
bookmarks | integer | Number of bookmarks created during the session. |
resolved_captchas | integer | Number of captchas resolved during the session. |
Possible reason_type Values
| Value | Description |
|---|---|
license_retail | Content accessed through a retail license. |
administrator_user | Content accessed by an administrator. |
free_issue | Content accessed because it is free. |
preview_issue | Content preview access enabled. |
free_access | Content accessed via integration with free access enabled. |
bought_issue | Content purchased by the user. |
assigned_issue | Content assigned manually by an administrator. |
gifted_issue | Content gifted to the user. |
external_permissions | Access through integration of reading permissions. |
subscription_with_collections | Access through a subscription with content collections. |
global_subscription | Access through a subscription granting global content access. |
lti_and_entry_point_free_access | Access through LTI integration. |
saml_and_entry_point_free_access | Access through SAML integration. |
ip_and_entry_point_free_access | Access through IP range integration. |
In cases where reason_type is subscription_with_collections or global_subscription, reason_value will contain the subscription plan ID.
info
The plan id can be found HERE