Endpoints reference

POST /v1/exports

This endpoint allows for creating a new export job.

These parameters have to be provided in the body of the request.

nameRequired. 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:

frequency.value

Required. Either “once”, “daily” or “hourly” (see Enumerations)

frequency.dateRange.from

Required only if frequency.value is “once”. The value must be a valid ISO 8601 date string. It should be anterior to frequency.dateRange.to, but not anterior to the project data retention period.

frequency.dateRange.to

Required only if frequency.value is “once”. The value must be a valid ISO 8601 date string. It should be posterior but not more than 7 days after frequency.dateRange.from.

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:

fieldName

Required. A valid fieldName corresponding to the name property of the fields that can be listed via the /v1/exportable-fields endpoint. You cannot specify a fieldName more than once, expcept for the special values “custom_var” and “dynamic_var” (used to export custom or dynamic variables).

aliasName

An alias that will be used to rename the exported field in the output file.

customVarPosition

Required only if “custom_var” is specified as fieldName. The custom variable position. Must be between 1 and 20 inclusive. To learn more about custom variables, see this documentation. To list custom variables available on the authenticated project, see the /v1/custom_vars endpoint.

dynamicVarKey

Required only if “dynamic_var” is specified as fieldName. The dynamic variable key. To learn more about dynamic variables, see this documentation. To list dynamic variables available on the authenticated project, see the /v1/dynamic_var_keys endpoint.

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 /v1/segment endpoint.

Terminal window
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Test API POST",
"format": "JSONL",
"scope": "sessions",
"frequency": {
"value": "daily"
},
"fields": [
{
"fieldName": "project_id",
},
{
"fieldName": "session_id",
}
],
"deviceLabel": "all",
"segmentId": 123
}'
Terminal window
curl --location --request POST 'https://api.contentsquare.com/v1/exports' \
--header 'Authorization: Bearer <your_access_token>' \
--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
}'
{
"payload": {
"jobId": 1372
},
"success": true
}

Get the list of all export jobs

Section titled 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).

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)

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exports?state=completed' \
--header 'Authorization: Bearer <your_access_token>'
{
"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

Section titled 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.

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.
Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exports/successful-runs' \
--header 'Authorization: Bearer <your_access_token>'
{
"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": "JSONL",
"scope": "views",
"frequency": "string",
"nbOfFiles": 0
}
],
"success": true
}

GET /v1/exports/{jobId}

This endpoint allows for retrieving a specific job with its ID.

None.

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1234' \
--header 'Authorization: Bearer <your_access_token>'
{
"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": "JSONL",
"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

Section titled 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.

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)

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs' \
--header 'Authorization: Bearer <your_access_token>'
{
"payload": [
{
"jobRunId": 0,
"startDate": "2021-05-02T16:51:51.004Z",
"state": "CREATED",
"endDate": "2021-05-02T16:51:51.004Z",
"completionRate": 0
}
],
"success": true
}

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.

None.

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs/67226' \
--header 'Authorization: Bearer <your_access_token>'
{
"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

Section titled 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).

scope (string)

Required. To filter based on the job scope (see Enumerations)

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/exportable-fields?scope=sessions' \
--header 'Authorization: Bearer <your_access_token>'
{
"payload": [
{
"name": "string",
"description": "string",
"example": "string",
"aliases": ["string"],
"parameters": ["string"]
}
],
"success": true
}

Get the list of custom variables

Section titled 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

No Parameters

Terminal window
curl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \
--header 'Authorization: Bearer <your_access_token>'
{
"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

Section titled 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

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.

Terminal window
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 <your_access_token>'
{
"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
}