Raw Data API
The Contentsquare Raw Data API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Not a developer? Contact your CSM. They will direct you to the best solution to meet your data needs.
- Base URL of the API: https://api.contentsquare.com
- Current Version of the API: 1.0
What is Contentsquare?
Contentsquare is a next-gen Analytics tool that helps you understand how and why your users are interacting with your app, mobile and websites.
Contentsquare allows its clients to create and manage export jobs to extract raw data that we rely on for our analytics. For a complete documentation of how to create jobs in the Contentsquare platform, refer to the documentation included in the help center or provided by your CSM.
By extracting raw data in downloadable files, clients can perform their own analyses for various use cases (e.g. business intelligence, data science). And they can store this data in their own infrastructure, allowing to go beyond the contractual data retention period provided by Contentsquare.
What this API is about
Use this API to programmatically create export jobs and retrieve the exported files. Currently, you can't use the API to update an existing export job. Edit export jobs for your project in the Contentsquare console (Data Export tab).
This API allows for extracting raw data, as opposed to aggregated data. To retrieve the aggregated data of your Contentsquare analyses modules, use the Metrics API.
You can extract raw data at the pageview or session level.
To understand how the export API works, you should understand the basic objects that you will manipulate via the provided endpoints.
What is a job?
A job is the abstract definition of an extraction task. A job definition includes:
- A name for the job
- A file format ("CSV", "CSVWithNames" or "JSONEachRow")
- A scope ("sessions" or "views")
- A frequency ("daily" or "once"): a daily job will run every day to extract the last day of data (the job is triggered every day at midnight UTC + 4 hours); a "once" job is triggered immediately after creation or is queued if another once job is running.
- A date range: only required for a "once" job, and not to exceed 7 days; not required for daily jobs (extraction is automatically run for the last day everyday)
- The fields to extract (e.g
session_id
): extractable fields will depend on the scope - The filters (e.g "deviceId")
What is a job run?
A job run is a specific instance of a job. For example, if a daily job has been defined, a job run represents the execution of this job on a specific day.
What is a job run part?
Job runs will generate several files to be downloaded. A job run part corresponds to a specific file.
Authentication
The Contentsquare Raw Data API requires API keys to authenticate requests. As an administrator, you can manage your API keys in the Contentsquare console.
API keys are created at the project level.
Your API keys carry many privileges, so keep them secure. Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API is performed by providing an API key as a Bearer token. Use Authorization: Bearer <YOUR_API_KEY>
in your HTTP request header.
All API requests must be authenticated and made over HTTPS. Calls made over HTTP will fail.
Limits
- You cannot create more than 5 API keys per project.
- The data retention period for the generated files is 7 days. Passed this period, you will not be able to download them anymore. If you missed some files from a daily job for example, keep in mind that you can still create a one-time ("once") job to retrieve the data a posteriori.
- For one-time jobs, you cannot extract data for a date range including more than 7 days.
Enumerations
You will find below a summary table of the enumerations used in the request or response payloads.
deviceId (integer) |
|
---|---|
format (string) | Required. Beginning of date range for analysis.
|
frequency (string) |
|
scope (string) |
|
job state |
|
job run state |
|
Endpoints reference
API key information
/v1/me
This endpoint provides information about the current API Key and the related project.
Request example
curl --location --request GET 'https://api.contentsquare.com/v1/me' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": {
"keyName": "Contentsquare customer test",
"projectId": 162,
"projectName": "Contentsquare.com",
"createdAt": "2019-09-04T13:22:17.000Z"
},
"success": true
}
Create an export job
POST /v1/exports
This endpoint allows for creating a new export job.
Parameters
These parameters have to be provided in the body of the request.
name |
Required. The name of the export. Must not be empty. | ||||||||
---|---|---|---|---|---|---|---|---|---|
format | Required. The file format of the export output. Must be one of the allowed values (see Enumerations) | ||||||||
scope | Required. The scope of the export. Must be one of the allowed values (see Enumerations) | ||||||||
frequency | Required. The frequency of the export. Child parameters:
| ||||||||
fields | Required. The list of fields to export. To list the exportable fields for a given scope, see the dedicated endpoint documented below. Child parameters:
| ||||||||
deviceLabel | Required. A device filter. Can be either "all", "desktop" , "mobile" or "tablet". | ||||||||
segmentId | Optional. A valid segmentId. If no segment is provided, the data for
all users will be exported. To retrieve the list of available segments for
the project, you can call the |
Request example 1
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <yourProjectApiKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Test API POST",
"format": "JSONEachRow",
"scope": "sessions",
"frequency": {
"value": "daily"
},
"fields": [
{
"fieldName": "project_id",
},
{
"fieldName": "session_id",
}
],
"deviceLabel": "all",
"segmentId": 123
}'
Request example 2
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <yourProjectApiKey>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Test API POST",
"format": "CSV",
"scope": "views",
"frequency": {
"value": "once",
"dateRange": {
"from": "2023-02-14T00:00:00.000Z",
"to": "2023-02-15T23:59:59.999Z"
}
},
"fields": [
{
"fieldName": "session_id",
"aliasName": "Session ID"
},
{
"fieldName": "view_number",
"aliasName": "View number in session"
},
{
"fieldName": "custom_var",
"customVarPosition": 2,
"aliasName": "My Custom Variable of index 2"
},
{
"fieldName": "dynamic_var",
"dynamicVarKey": "AB Test",
"aliasName": "Experiment"
}
],
"deviceLabel": "desktop",
"segmentId": 123
}'
Response example
{
"payload": {
"jobId": 1372
},
"success": true
}
Get the list of all export jobs
GET /v1/exports
This endpoint provides the list of all the available export jobs (be they in status active, suspended, computing or completed).
Parameters
format (string) | Optional. To filter based on the export format (see Enumerations) |
---|---|
frequency (string) | Optional. To filter based on the export frequency (see Enumerations) |
limit (integer) | Optional. To change the page size of results (25 by default, 100 max). |
order (string) | Optional. To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the jobId. |
page (integer) |
Optional. The page of results to retrieve. |
scope (string) | Optional. To filter based on the job scope (see Enumerations) |
state (string) | Optional. To filter based on the job status (see Enumerations) |
Request example
curl --location --request GET 'http://api.contentsquare.com/v1/exports?state=completed' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"jobId": 0,
"name": "string",
"ownerId": 0,
"lastUpdatorId": 0,
"accountId": 0,
"nextFrom": "2021-05-02T16:22:43.439Z",
"nextTo": "2021-05-02T16:22:43.439Z",
"projectIds": [0],
"state": "ACTIVE",
"createdAt": "2021-05-02T16:22:43.439Z",
"format": "JSON",
"scope": "views",
"frequency": "string",
"fields": [
{
"fieldName": "string",
"aliasName": "string"
}
],
"lastRunTime": "2021-05-02T16:22:43.439Z",
"nextRunTime": "2021-05-02T16:22:43.439Z",
"updatedAt": "2021-05-02T16:22:43.439Z",
"filters": {
"deviceId": 0
}
}
],
"success": true
}
nextFrom
and nextTo
represents the next date range that will be extracted, while lastRunTime
and nextRunTime
indicates when the last and next execution started / will start.
Get the list of all successful job runs
GET /v1/exports/successful-runs
This endpoint provides the list of all the jobs runs that completed successfully. It is useful to quickly find which jobs have generated extraction files to be downloaded.
Parameters
limit (integer) | Optional. To change the page size of results (25 by default, 100 max). |
---|---|
order (string) | Optional. To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the jobId. |
page (integer) |
Optional. The page of results to retrieve. |
Request example
curl --location --request GET 'http://api.contentsquare.com/v1/exports/successful-runs' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"jobId": 0,
"jobRunId": 0,
"name": "string",
"projectIds": [0],
"from": "2021-05-02T16:40:14.022Z",
"to": "2021-05-02T16:40:14.022Z",
"completionTime": "2021-05-02T16:40:14.022Z",
"format": "JSON",
"scope": "views",
"frequency": "string",
"nbOfFiles": 0
}
],
"success": true
}
Get a specific job
GET /v1/exports/{jobId}
This endpoint allows for retrieving a specific job with its ID.
Parameters
None.
Request example
curl --location --request GET 'http://api.contentsquare.com/v1/exports/1234' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": {
"jobId": 0,
"name": "string",
"ownerId": 0,
"lastUpdatorId": 0,
"accountId": 0,
"nextFrom": "2021-05-02T16:50:29.301Z",
"nextTo": "2021-05-02T16:50:29.301Z",
"projectIds": [0],
"state": "ACTIVE",
"createdAt": "2021-05-02T16:50:29.301Z",
"format": "JSON",
"scope": "views",
"frequency": "string",
"fields": [
{
"fieldName": "string",
"aliasName": "string"
}
],
"lastRunTime": "2021-05-02T16:50:29.301Z",
"nextRunTime": "2021-05-02T16:50:29.301Z",
"updatedAt": "2021-05-02T16:50:29.301Z",
"filters": {
"deviceId": 0
}
},
"success": true
}
nextFrom
and nextTo
represents the next date range that will be extracted, while lastRunTime
and nextRunTime
indicates when the last and next execution started / will start.
Get the list of all job runs of a job
GET /v1/exports/{jobId}/runs
This endpoint provides the list of all the job runs related to a specific job.
Parameters
limit (integer) | Optional. To change the page size of results (25 by default, 100 max). |
---|---|
order (string) | Optional. To change the order of the results list ("ASC" or "DESC", "DESC" by default). Ordering is based on the jobId. |
page (integer) |
Optional. The page of results to retrieve. |
state (string) | Optional. To filter based on the job status (see Enumerations) |
Request example
curl --location --request GET 'http://api.contentsquare.com/v1/exports/1354/runs' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"jobRunId": 0,
"startDate": "2021-05-02T16:51:51.004Z",
"state": "CREATED",
"endDate": "2021-05-02T16:51:51.004Z",
"completionRate": 0
}
],
"success": true
}
Get a specific job run
GET /v1/exports/{jobId}/runs/{runId}
This endpoint allows for retrieving a specific job run with its ID. The response includes all the extraction files available for download if any (in the files
field). The files can be downloaded via the provided URL in the url
field. Files will not be available for download after the expirationDate
.
Parameters
None.
Request example
curl --location --request GET 'http://api.contentsquare.com/v1/exports/1354/runs/67226' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": {
"jobRunId": 0,
"startDate": "2021-05-02T16:54:55.983Z",
"state": "CREATED",
"files": [
{
"partId": 0,
"fileSize": 0,
"url": "string",
"expirationDate": "2021-05-02T16:54:55.983Z"
}
],
"endDate": "2021-05-02T16:54:55.983Z",
"completionRate": 0
},
"success": true
}
Get the list of all exportable fields
GET /v1/exportable-fields
This endpoint allows for retrieving all fields that can be extracted for a specified scope (the list of fields will depend on the scope).
Parameters
scope (string) | Required. To filter based on the job scope (see Enumerations) |
---|
Request example
curl --location --request GET 'https://api.contentsquare.com/v1/exportable-fields?scope=sessions' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"name": "string",
"description": "string",
"example": "string",
"aliases": ["string"],
"parameters": ["string"]
}
],
"success": true
}
Get the list of custom variables
GET /v1/custom-vars
This endpoint allows for retrieving all the custom variables available on a project. To learn more about custom variables, see this documentation
Parameters
No Parameters
Request example
curl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"position": 2,
"key": "dataType",
"values": [
"journey",
"recording",
"zoning"
]
},
{
"position": 3,
"key": "pageType",
"values": [
"checkoutstep 1"
"checkoutstep 2",
"checkoutstep 3",
]
},
{
"position": 1,
"key": "Goal achieved",
"values": [
"false",
"true"
]
}
],
"success": true
}
Get the list of dynamic variables
GET /v1/dynamic-var-keys
This endpoint allows for retrieving all the dynamic variables available on a project between two dates. To learn more about custom variables, see this documentation
Parameters
from | Required. Start date of the query date range. The value must be a valid ISO 8601 date string. |
---|---|
to | Required. End date of the query date range. The value must be a valid ISO 8601 date string. |
Request example
curl --location --request GET 'https://api.contentsquare.com/v1/dynamic-var-keys?from=2023-02-10T00:00:00&to=2023-02-17T00:00:00' \
--header 'Authorization: Bearer <yourProjectApiKey>'
Response example
{
"payload": [
{
"key": "AB Test",
"type": "string"
},
{
"key": "Traffic Source",
"type": "string"
},
{
"key": "VoC feedback score",
"type": "string"
},
{
"key": "Web Analytics Segment",
"type": "string"
}
],
"success": true
}
Fields reference
Session-level fields
Summary of available fields
Geography
city
City associated to the user.
Data type | Example value |
---|---|
String | Paris |
country_code
Country associated to the user.
Data type | Example value |
---|---|
String | FR |
language
Language associated to the user.
Data type | Example value |
---|---|
String | fr |
Identifiers
project_id
Unique project identifier.
Data type | Example value |
---|---|
Integer | 42 |
user_id
Unique user identifier.
This identifier is saved within a cookie named _cs_id
which has a lifetime of 13 months.
Data type | Example value |
---|---|
Integer | 5066017809039612144 |
Mobile (CS App)
Those fields are only available for Apps projects.
app_events.event_name
List of the app event names.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(String) | ['appStartEvent', 'appShowEvent', 'appHideEvent'] |
app_events.event_time
List of dates and UTC times of the app events.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2020-06-24 17:07:42', '2020-06-24 17:07:42', '2020-06-24 17:08:53'] |
app_events.event_type
List of the app events types related to the session:
0
: app start1
: app show2
: app hide
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [0, 1, 2] |
app_events.view_number
The pageview number related to the event.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [0, 0, 1] |
app_version
The client app version.
Data type | Example value |
---|---|
Integer | 2814771241943040 |
density
Pixel density measured in PPI, i.e. to the number of Pixels Per Inch on the display.
Data type | Example value |
---|---|
Float | 38912.312 |
manufacturer
The mobile device manufacturer.
Data type | Example value |
---|---|
String | HUAWEI |
model
The mobile device model.
Data type | Example value |
---|---|
String | SNE-LX1 |
os_version
Version of Android or iOS used by the visitor (iOS 13.1. or iOS 13.2 etc.)
Data type | Example value |
---|---|
Integer | 2251799813685248 |
Session
dynamic_vars_int_in_session.key
Array of keys of integer dynamic variables extracted from the website datalayer.
Each variable has the same index in all dynamic_vars_int_in_session.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_name_123', VAR_name_456'] |
dynamic_vars_int_in_session.value
Array of values of integer dynamic variables extracted from the website datalayer.
Each variable has the same index in all dynamic_vars_int_in_session.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [123, 456] |
dynamic_vars_string_in_session.key
Array of keys of string dynamic variables extracted from the website datalayer.
Each variable has the same index in all dynamic_vars_string_in_session.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_name_123', VAR_name_456'] |
dynamic_vars_string_in_session.value
Array of values of string dynamic variables extracted from the website datalayer.
Each variable has the same index in all dynamic_vars_string_in_session.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_value_123', 'VAR_value_456'] |
is_excludable
Values are either 1 or 0, to indicate whether the session is generated from bot traffic (1) or not (0).
Data type | Example value |
---|---|
Integer | 1 |
is_recorded
For Session Replay, indicates whether the session was collected (1) or not (0). This field can only be exported for projects with access to Session Replay.
Data type | Example value |
---|---|
Integer | 1 |
session_add_to_cart_items.add_to_cart_time
Those values are populated when sending an add to cart event to Contentsquare.
Array of the datetimes when the items were added to cart.
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2020-06-24 17:07:42', '2020-06-24 17:07:42', '2020-06-24 17:08:53'] |
session_add_to_cart_items.add_to_cart_view_number
Those values are populated when sending an add to cart event to Contentsquare.
Array of the page view numbers (position in session) from which items were added to cart.
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 5, 3] |
session_add_to_cart_items.catalog_id
Those values are populated when sending an add to cart event to Contentsquare.
Array of the catalog identifiers of the items added to the cart. Will be 0 if the project has no Merchandising catalog set-up.
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [71893, 0, 991893] |
session_add_to_cart_items.is_in_transaction
Those values are populated when sending an add to cart event to Contentsquare.
Array of the booleans indicating whether the items added to cart were purchased (1) or not (0).
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [0, 0, 1] |
session_add_to_cart_items.product_id_hashed
Those values are populated when sending an add to cart event to Contentsquare.
Array of the items' hashed identifiers. Will be '0' if the project has no Merchandising catalog set-up.
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['3976139', '0', '30230O013'] |
session_add_to_cart_items.sku
Those values are populated when sending an add to cart event to Contentsquare.
Array of the SKUs of the items added to cart.
Each item has the same index in all session_add_to_cart_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['987897849120', '47807017348784'] |
session_date
Session start date.
Data type | Example value |
---|---|
String | 2020-07-26 |
session_duration_msec
Session duration in milliseconds.
Data type | Example value |
---|---|
Integer | 881633 |
session_id
Unique session identifier.
Data type | Example value |
---|---|
Integer | 5066017809039605767 |
session_number
The number of sessions of the user (takes into account how many times the user visited before).
Data type | Example value |
---|---|
Integer | 7 |
session_number_of_transactions
Number of transactions placed during the session.
Data type | Example value |
---|---|
Integer | 2 |
session_number_of_views
The number of page views in the session.
Data type | Example value |
---|---|
Integer | 5 |
session_replay_link
The session replay link, if the session was collected (see is_recorded
field).
This field can only be exported for projects with access to Session Replay.
Data type | Example value |
---|---|
String | https://app.contentsquare.com/quick-playback/index.html?pid=... |
session_time
Session start date and UTC time.
Data type | Example value |
---|---|
String | 2020-07-26 05:53:04 |
session_transaction_items.catalog_id
Those values are populated when sending a transaction event to Contentsquare.
Array of the catalog identifiers of the purchased items. Will be 0 if the project has no Merchandising catalog set-up.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [71893, 0, 991893] |
session_transaction_items.id
Those values are populated when sending a transaction event to Contentsquare.
Array of the transactions identifiers.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['ABC287632', 'ABC1290873'] |
session_transaction_items.product_id_hashed
Those values are populated when sending a transaction event to Contentsquare.
Array of the items' hashed identifiers. Will be '0' if the project has no Merchandising catalog set-up.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['3976139', '0', '30230O013'] |
session_transaction_items.quantity
Those values are populated when sending a transaction event to Contentsquare.
Array of the purchased quantity of the items.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 4, 1] |
session_transaction_items.revenue_cents
Those values are populated when sending a transaction event to Contentsquare.
Array of the revenues (in cents) of the purchased items.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [89211, 450] |
session_transaction_items.sku
Those values are populated when sending an add to cart event to Contentsquare.
Array of the SKUs of the purchased items.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['987897849120', '47807017348784'] |
session_transaction_items.transaction_time
Those values are populated when sending a transaction event to Contentsquare.
Array of the datetimes when the items were purchased.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2020-06-24 17:07:42', '2020-06-24 17:07:42', '2020-06-24 17:08:53'] |
session_transaction_items.transaction_view_number
Those values are populated when sending a transaction event to Contentsquare.
Array of the page view numbers (position in session) from which items were purchased.
Each item has the same index in all session_transaction_items.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 5, 3] |
session_transactions_revenue_cents
Total revenue generated by the session (in US dollar cents).
Data type | Example value |
---|---|
Integer | 37655 |
referer_url
The referring URL to the first page view of the session.
Data type | Example value |
---|---|
String | https://www.google.fr/ |
Technology
browser_major_version
The browser major version.
Data type | Example value |
---|---|
Integer | 83 |
browser_name
The browser name.
Data type | Example value |
---|---|
String | Chrome |
browser_version
The browser version.
Data type | Example value |
---|---|
String | 83.0.4103.116 |
device_id
Unique device identifier:
0
: Unknown1
: Desktop2
: Mobile (Web)3
: Tablet (Web)4
: Mobile (App)5
: Tablet (App)
Data type | Example value |
---|---|
Integer | 2 |
platform_name
The operating system name.
Data type | Example value |
---|---|
String | Windows |
platform_version
The operating system version.
Data type | Example value |
---|---|
Integer | 10 |
screen_height
The screen height in pixels.
Data type | Example value |
---|---|
Integer | 700 |
screen_width
The screen width in pixels.
Data type | Example value |
---|---|
Integer | 1280 |
Pageview-level fields
Summary of available fields
Errors
errors.message
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of descriptions of the JavaScript error events.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(String) | ['Uncaught Error: Mismatched anonymous define() module...', 'Uncaught TypeError: Cannot read properties of undefined'] |
errors.error_time
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of timestamps of the JavaScript error events.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2020-07-11 18:55:41','2020-07-11 18:55:42'] |
errors.filename
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of URLs of the files where the JavaScript error events occurred.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(String) | ['https://some.site.com/static/scripts/somelib.js','https://someother.site.com/static/scripts/someotherlib.js'] |
errors.line_number
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of line numbers in the files where the JavaScript error events occurred.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(Number) | [2, 1998] |
errors.col_number
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of column numbers in the files where the JavaScript error events occurred.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(Number) | [55, 44] |
errors.group_id
This field is only available for CS Find & Fix clients. Contact your CSM if you don't have access to the Errors module.
The list of Group IDs of the JavaScript error events, used to regroup similar errors together in Contentsquare.
Each event has the same index in all errors.*
fields.
Data type | Example value |
---|---|
Array(Number) | [2406037528566246307, 17923195893144918451] |
errors_api.url
This field is only available for CS Find & Fix clients who have access to the API errors feature. Contact your CSM if you don't have access to this feature.
The list of URL endpoints of the API error events.
Each event has the same index in all errors_api.*
fields.
Data type | Example value |
---|---|
Array(String) | ['https://some.site.com/login', 'https://someother.site.com/login'] |
errors_api.method
This field is only available for CS Find & Fix clients who have access to the API errors feature. Contact your CSM if you don't have access to this feature.
The list of HTTP method of the API error events.
Each event has the same index in all errors_api.*
fields.
Data type | Example value |
---|---|
Array(String) | ['GET', 'POST'] |
errors_api.status_code
This field is only available for CS Find & Fix clients who have access to the API errors feature. Contact your CSM if you don't have access to this feature.
The list of HTTP status codes of the API error events.
Each event has the same index in all errors_api.*
fields.
Data type | Example value |
---|---|
Array(Number) | [500, 501] |
errors_api.request_time
This field is only available for CS Find & Fix clients who have access to the API errors feature. Contact your CSM if you don't have access to this feature.
The list of the API call start timestamps of the API error events.
Each event has the same index in all errors_api.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2023-01-19 01:50:36', '2023-01-21 01:50:36'] |
errors_api.group_id
This field is only available for CS Find & Fix clients who have access to the API errors feature. Contact your CSM if you don't have access to this feature.
The list of Group IDs of the API error events, used to regroup similar errors together in Contentsquare.
Each event has the same index in all errors_api.*
fields.
Data type | Example value |
---|---|
Array(Number) | [2406037528566246307, 17923195893144918451] |
custom_errors.message
This field is only available for CS Find & Fix clients who have access to the custom errors feature. Contact your CSM if you don't have access to this feature.
The list of descriptions of the custom error events.
Each event has the same index in all custom_errors.*
fields.
Data type | Example value |
---|---|
Array(String) | ['An error happened', 'Another error happened'] |
custom_errors.error_time
This field is only available for CS Find & Fix clients who have access to the custom errors feature. Contact your CSM if you don't have access to this feature.
The list of timestamps of the custom error events.
Each event has the same index in all custom_errors.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2023-01-19 01:50:36', '2023-01-20 01:50:36'] |
custom_errors.attributes
This field is only available for CS Find & Fix clients who have access to the custom errors feature. Contact your CSM if you don't have access to this feature.
The list of key/value pairs of custom tags of the custom error events. Each event can have a list of several key/value pairs.
Each event has the same index in all custom_errors.*
fields.
Data type | Example value |
---|---|
Array(Array(String)) | [[('severity', 'high'), ('category', 'login')]] |
custom_errors.group_id
This field is only available for CS Find & Fix clients who have access to the custom errors feature. Contact your CSM if you don't have access to this feature.
The list of Group IDs of the custom error events, used to regroup similar errors together in Contentsquare.
Each event has the same index in all custom_errors.*
fields.
Data type | Example value |
---|---|
Array(Number) | [2406037528566246307, 17923195893144918451] |
Events
has_all_interaction_events
If we got all kinds of events (clicks, mouse moves etc.) on the page, value is 1, else 0.
Data type | Example value |
---|---|
Integer | 0 |
page_events
List of page events.
Data type | Example value |
---|---|
Array(String) | ['Config: Release_20201112','FB_MD_Feedback Submitted'] |
raw_clicks.event_time
The list of the dates and UTC times of the click events.
Each event has the same index in all raw_click.*
fields.
Data type | Example value |
---|---|
String | ['2020-07-26 05:53:04', '2020-07-26 05:54:22'] |
raw_clicks.event_type
The list of the raw events types. Can be either:
5
: CLICK10
: CHANGE11
: FOCUS12
: BLUR
Each event has the same index in all raw_click.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [5, 11] |
raw_clicks.relative_time_ms
Number of milliseconds between the beginning of the view and each of the raw events.
Each event has the same index in all raw_click.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [3981, 1782] |
raw_clicks.target_blank_field
Whether the event was an interaction with a blank field in a form. Can be either:
0
: Not applicable1
: False2
: True
Each event has the same index in all raw_click.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [1, 2] |
raw_clicks.target_path
The list of the paths that were clicked.
Each event has the same index in all raw_click.*
fields.
Data type | Example value |
---|---|
Array(String) | ['html(0)>form(0)>div(0)>button(0)', 'html(0)>button(0)'] |
targets_clicks.path
The list of the paths of the target zone.
Each target has the same index in all targets_clicks.*
fields.
Data type | Example value |
---|---|
Array(String) | ['html(0)>form(0)>div(0)>button(0)', 'html(0)>button(0)'] |
targets_clicks.sum
The number of times the target was clicked on (aggregation of raw_clicks
).
Each target has the same index in all targets_clicks.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 1] |
targets_clicks.time_before_msec
The delay between the loading of the page and the time the user clicked on the target for the first time (in milliseconds).
Each target has the same index in all targets_clicks.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [779, 391] |
targets_clicks.time_between_last_hover_and_first_click
Time before last hover and first select the target (in milliseconds).
Each target has the same index in all targets_clicks.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [13533, 30791] |
targets_focus.path
List of the raw path of the targets.
Each target has the same index in all targets_focus.*
fields.
Data type | Example value |
---|---|
Array(String) | ['html(0)>form(0)>div(0)>button(0)', 'html(0)>button(0)'] |
targets_focus.sum
List of the number of times the target was focused on.
Each target has the same index in all targets_focus.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 5] |
targets_focus.time_before_msec
List of times before first focus on a zone (in milliseconds).
Each target has the same index in all targets_focus.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [13533, 30791] |
targets_hover.path
List of the raw path of the targets.
Each target has the same index in all targets_hover.*
fields.
Data type | Example value |
---|---|
Array(String) | ['html(0)>form(0)>div(0)>button(0)', 'html(0)>button(0)'] |
targets_hover.sum
List of the number of times the target was hovered on.
Each target has the same index in all targets_hover.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2, 5] |
targets_hover.sum_times
List of the total time the target was hovered on (in milliseconds).
Each target has the same index in all targets_hover.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [2563 ,252] |
targets_hover.time_before_msec
List of times before first hover on a zone (in milliseconds).
Each target has the same index in all targets_hover.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [13533, 30791] |
Frustration
Those fields are only exportable for projects with an access to the frustration score in Contentsquare.
any_api_error_ind
A normalized score between 0 and 1 to indicate whether any API error occurred on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
any_js_error_ind
A normalized score between 0 and 1 to indicate whether any JavaScript error occurred on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
api_error_after_click_ind
A normalized score between 0 and 2 to indicate whether API errors occurred after some clicks. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
excessive_hovers_ind
A normalized score between 0 and 2 to indicate whether excessive hovers occurred on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 1.64 |
frustration_score
A normalized score between 0 and 100 computed based on all other frustration indicators, to express an overall frustration level on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
is_watchable
Whether the page is considered watchable (1) or not (0). Only pages that are watchable have a frustration score. To be considered watchable, the page view must respect the following conditions:
- Be part of a collected session (
is_recorded
= 1) - Its duration should be at least 2 seconds
- There should be at least 2 clicks on the page
This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Integer | 0 |
js_error_after_click_ind
A normalized score between 0 and 2 to indicate whether any JavaScript error occurred after clicks on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 1.64 |
loading_time_ind
A normalized score between 0 and 1 to indicate whether loading time was slow on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
multiple_button_interaction_ind
A normalized score between 0 and 2 to indicate multiple interactions on button targets on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 1.64 |
multiple_field_interaction_ind
A normalized score between 0 and 2 to indicate multiple interactions on field targets on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 1.64 |
multiple_used_targets_ind
A normalized score between 0 and 1 to indicate multiple interactions on targets on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
no_clicks_on_page_ind
A normalized score between 0 and 1 to indicate low activity on the page. This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 0.27 |
rage_click_all_targets_ind
A normalized score between 0 and 2 to indicate rage clicks (multiple clicks in a short time frame). This field is only exportable for projects with an access to the frustration score in Contentsquare.
Data type | Example value |
---|---|
Float | 1.64 |
Geography
city
City associated to the user.
Data type | Example value |
---|---|
String | Paris |
country_code
Country associated to the user.
Data type | Example value |
---|---|
String | FR |
language
Language associated to the user.
Data type | Example value |
---|---|
String | fr |
Identifiers
project_id
Unique project identifier.
Data type | Example value |
---|---|
Integer | 42 |
user_id
Unique user identifier.
This identifier is saved within a cookie named _cs_id
which has a lifetime of 13 months.
Data type | Example value |
---|---|
Integer | 5066017809039612144 |
Mobile (CS App)
app_events.event_name
List of the app event names.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(String) | ['appStartEvent', 'appShowEvent', 'appHideEvent'] |
app_events.event_time
List of dates and UTC time of the app events.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(String) | ['2020-06-24 17:07:42', '2020-06-24 17:07:42', '2020-06-24 17:08:53'] |
app_events.event_type
List of the app events types related to the session:
0
: app start1
: app show2
: app hide
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [0, 1, 2] |
app_events.view_number
The pageview number related to the event.
Each app event has the same index in all app_events.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [0, 0, 1] |
app_version
The client app version.
Data type | Example value |
---|---|
Integer | 2814771241943040 |
density
Pixel density measured in PPI, i.e. to the number of Pixels Per Inch on the display.
Data type | Example value |
---|---|
Float | 38912.312 |
manufacturer
The mobile device manufacturer.
Data type | Example value |
---|---|
String | HUAWEI |
model
The mobile device model.
Data type | Example value |
---|---|
String | SNE-LX1 |
os_version
Version of Android or iOS used by the visitor (iOS 13.1. or iOS 13.2 etc.)
Data type | Example value |
---|---|
Integer | 2251799813685248 |
screen_name
The screen name.
Data type | Example value |
---|---|
String | Showroom |
targets_drag.finger_direction
List of finger directions related to the swipe events:
1
: up2
: down3
: left4
: right5
: complex
Each target has the same index in all targets_drag.*
fields.
Data type | Example value |
---|---|
List(Integer) | [2, 5] |
targets_drag.sum
The number of times the target was swiped.
Data type | Example value |
---|---|
List(Integer) | [3, 1] |
Each target has the same index in all targets_drag.*
fields.
targets_drag_and_flick.finger_direction
List of finger directions related to the swipe or fast swipe events:
1
: up2
: down3
: left4
: right5
: complex
Each target has the same index in all targets_drag_and_flick.*
fields.
Data type | Example value |
---|---|
List(Integer) | [2, 5] |
targets_drag_and_flick.orientation
List of orientations related to the swipe or fast swipe events:
0
: portrait1
: landscape
Each target has the same index in all targets_drag_and_flick.*
fields.
Data type | Example value |
---|---|
List(Integer) | [1, 0] |
targets_drag_and_flick.sum
Each target has the same index in all targets_drag_and_flick.*
fields.
Data type | Example value |
---|---|
List(Integer) | [3, 1] |
Each value has the same array index as their corresponding targets_drag_and_flick.finger_direction
and targets_drag_and_flick.orientation
.
targets_flick.finger_direction
List of finger directions related to the fast swiped events:
1
: up2
: down3
: left4
: right5
: complex
Each target has the same index in all targets_flick.*
fields.
Data type | Example value |
---|---|
List(Integer) | [2, 5] |
targets_flick.sum
The number of times the target was fast swiped.
Data type | Example value |
---|---|
List(Integer) | [3, 1] |
Each target has the same index in all targets_flick.*
fields.
targets_long_press.sum
List of the number of times the target was long press (a target is considered long pressed after at least 500ms).
Data type | Example value |
---|---|
List(Integer) | [3, 1] |
targets_tap.responsive
List of values equal to 1 if the App reacted to the tap, else 0.
Each target has the same index in all targets_tap.*
fields.
Data type | Example value |
---|---|
Aray(Integer) | [0, 1] |
targets_tap.sum
List of the number of times the target was tapped.
Each target has the same index in all targets_tap.*
fields.
Data type | Example value |
---|---|
Aray(Integer) | [3, 1] |
targets_tap.time_before_msec
List of delays between the loading of the page and the time the user tap on the target for the first time (in milliseconds).
Each target has the same index in all targets_tap.*
fields.
Data type | Example value |
---|---|
Aray(Integer) | [31029, 26496] |
Page
custom_vars_view.key
Array of keys of custom variables extracted from the website datalayer.
Each variable has the same index in all custom_vars_view.*
fields.
Data type | Example value |
---|---|
Array(String) | ['pageType', 'page_error', 'user_logged'] |
custom_vars_view.position
Array of positions of custom variables extracted from the website datalayer.
Each variable has the same index in all custom_vars_view.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [1, 7, 16] |
custom_vars_view.value
Array of values of custom variables extracted from the website datalayer.
Each variable has the same index in all custom_vars_view.*
fields.
Data type | Example value |
---|---|
Array(String) | ['catalogsearch_result_index', '200', 'not_logged'] |
document_height
Page height in pixels.
Data type | Example value |
---|---|
Integer | 4326 |
document_width
Page width in pixels.
Data type | Example value |
---|---|
Integer | 1280 |
dom_interactive_after_msec
The time in milliseconds required before the user is able to interact with the page (although all resources may not be fully loaded yet).
Data type | Example value |
---|---|
Integer | 5356 |
dynamic_vars_int_in_view.key
Array of keys of integer dynamic variables extracted from the website datalayer of the pageview.
Each variable has the same index in all dynamic_vars_int_in_view.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_name_123', VAR_name_456'] |
dynamic_vars_int_in_view.value
Array of values of integer dynamic variables extracted from the website datalayer of the pageview.
Each variable has the same index in all dynamic_vars_int_in_view.*
fields.
Data type | Example value |
---|---|
Array(Integer) | [123, 456] |
dynamic_vars_string_in_view.key
Array of keys of string dynamic variables extracted from the website datalayer of the pageview.
Each variable has the same index in all dynamic_vars_string_in_view.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_name_123', VAR_name_456'] |
dynamic_vars_string_in_view.value
Array of values of string dynamic variables extracted from the website datalayer of the pageview.
Each variable has the same index in all dynamic_vars_string_in_view.*
fields.
Data type | Example value |
---|---|
Array(String) | ['VAR_value_123', 'VAR_value_456'] |
fully_loaded
The time in milliseconds required to fully load all the resources of the page, from initiation of the pageview to load completion in the browser.
Data type | Example value |
---|---|
Integer | 8186 |
is_first
If the page is the entry page then value is 1, otherwise value is 0.
Data type | Example value |
---|---|
Integer | 0 |
is_last
If the page is the exit page then value is 1, otherwise value is 0.
Data type | Example value |
---|---|
Integer | 1 |
last_hover_path
The last path the was hovered by the visitor.
Data type | Example value |
---|---|
String | html(0)>body(0)>div(4)>input(0) |
page_interaction_time_msec
Interaction time in milliseconds.
Data type | Example value |
---|---|
Integer | 4967 |
path
Path of the pageview URL.
Data type | Example value |
---|---|
String | /cs-squad-3307216025801.html |
prefix
Host of the pageview URL.
Data type | Example value |
---|---|
String | www.contentsquare.com |
query
Query of the pageview URL.
Data type | Example value |
---|---|
String | cs=42&lang=fr |
scheme
Protocol (HTTP or HTTPS).
Data type | Example value |
---|---|
String | https |
scroll_rate
The portion of the page which was displayed (in percentage points).
Data type | Example value |
---|---|
Float | 61.4 |
start_render
Timestamp sent by tag when the rendering of the page started.
Data type | Example value |
---|---|
Integer | 112 |
url
The complete URL of the page (concatenation of prefix, path and query).
Data type | Example value |
---|---|
String | https://contentsquare.com/?s=ux |
url_no_params
The URL of the page excluding query parameters (concatenation of prefix and path).
Data type | Example value |
---|---|
String | https://contentsquare.com/ |
view_duration_msec
Duration between the page view event time (view_time
) and the timestamp of the
last interaction event (in milliseconds).
Data type | Example value |
---|---|
Integer | 49118 |
view_number
The pageview number in the session.
Data type | Example value |
---|---|
Integer | 2 |
view_time
The pageview date and UTC time.
Data type | Example value |
---|---|
String | 2020-07-26 05:53:04 |
viewports.bottom_screen_position
Array of bottom positions of the screen of the user. A new value is appended in the array after each scroll event.
Data type | Example value |
---|---|
Array(Integer) | [754, 2332, 2620] |
viewports.exposition_time_msec
The exposition time in milliseconds of the areas that were exposed to the user. A new value is appended in the array after each scroll event.
Data type | Example value |
---|---|
Array(Integer) | [22740, 679, 1338] |
viewports.top_screen_position
Array of top positions of the screen of the user. A new value is appended in the array after each scroll event.
Data type | Example value |
---|---|
Array(Integer) | [0, 1578, 1866] |
window_height
Height of the window in which the page is opened.
Data type | Example value |
---|---|
Integer | 720 |
window_width
Width of the window in which the page is opened.
Data type | Example value |
---|---|
Integer | 1280 |
Session
is_excludable
Values are either 1 or 0, to indicate whether the session is generated from bot traffic (1) or not (0).
Data type | Example value |
---|---|
Integer | 1 |
is_recorded
For Session Replay, indicates whether the session was collected (1) or not (0).
Data type | Example value |
---|---|
Integer | 1 |
session_date
Session start date.
Data type | Example value |
---|---|
String | 2020-07-26 |
session_duration_msec
Session duration in milliseconds.
Data type | Example value |
---|---|
Integer | 881633 |
session_id
Unique session identifier.
Data type | Example value |
---|---|
Integer | 5066017809039605767 |
session_number
The number of sessions of the user (takes into account how many times the user visited before).
Data type | Example value |
---|---|
Integer | 7 |
session_number_of_transactions
Number of transactions placed during the session.
Data type | Example value |
---|---|
Integer | 2 |
session_number_of_views
The number of page views in the session.
Data type | Example value |
---|---|
Integer | 5 |
session_replay_link
The session replay link, if the session was collected (see is_recorded
field).
Data type | Example value |
---|---|
String | https://app.contentsquare.com/quick-playback/index.html?pid=... |
session_time
Session start date and UTC time.
Data type | Example value |
---|---|
String | 2020-07-26 05:53:04 |
session_transactions_revenue_cents
Total revenue generated by the session (in US dollar cents).
Data type | Example value |
---|---|
Integer | 37655 |
referer_url
The referring URL to the first page view of the session.
Data type | Example value |
---|---|
String | https://www.google.fr/ |
Speed Analysis
Those fields are only exportable for projects with an access to the Speed Analysis module in Contentsquare.
time_to_first_byte
Delay (in milliseconds) between the request for the web page and when the web browser received the first piece of data. This field is only exportable for projects with an access to the Speed Analysis module in Contentsquare.
Data type | Example value |
---|---|
Integer | 83 |
first_contentful_paint
Delay (in milliseconds) to render the first piece of content. This field is only exportable for projects with an access to the Speed Analysis module in Contentsquare.
Data type | Example value |
---|---|
Integer | 196 |
largest_contentful_paint
Delay (in milliseconds) to render the largest piece of content (part of Core Web Vitals). This field is only exportable for projects with an access to the Speed Analysis module in Contentsquare.
Data type | Example value |
---|---|
Integer | 297 |
cumulative_layout_shift
Score about the layout stability of the page rendering (part of Core Web Vitals). This field is only exportable for projects with an access to the Speed Analysis module in Contentsquare.
Data type | Example value |
---|---|
Integer | 7 |
first_input_delay
Delay (in milliseconds) between the first user interaction and when the web browser can handle it (part of Core Web Vitals). This field is only exportable for projects with an access to the Speed Analysis module in Contentsquare.
Data type | Example value |
---|---|
Integer | 42 |
Technology
browser_major_version
The browser major version.
Data type | Example value |
---|---|
Integer | 83 |
browser_name
The browser name.
Data type | Example value |
---|---|
String | Chrome |
browser_version
The browser version.
Data type | Example value |
---|---|
String | 83.0.4103.116 |
device_id
Unique device identifier:
0
: Unknown1
: Desktop2
: Mobile (Web)3
: Tablet (Web)4
: Mobile (App)5
: Tablet (App)
Data type | Example value |
---|---|
Integer | 2 |
platform_name
The operating system name.
Data type | Example value |
---|---|
String | Windows |
platform_version
The operating system version.
Data type | Example value |
---|---|
Integer | 10 |
screen_height
The screen height in pixels.
Data type | Example value |
---|---|
Integer | 700 |
screen_width
The screen width in pixels.
Data type | Example value |
---|---|
Integer | 1280 |