Getting Started
The Contentsquare Data Export 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. All API requests must be made over HTTPS.
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.{cloud}.contentsquare.com
- Current Version of the API: 1.0
What is Contentsquare?
Section titled 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
Section titled What this API is aboutUse 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.
A job is the abstract definition of an extraction task. A job definition includes:
- A name for the job
- A file format (“CSV” or “JSONL”)
- A scope (“sessions” or “views”)
- A frequency (“daily”, “hourly”, 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”)
Job runs
Section titled Job runsA 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.
Job run parts
Section titled Job run partsJob runs will generate several files to be downloaded. A job run part corresponds to a specific file.