Endpoints reference
Create an export job
Section titled Create an export jobPOST /v1/exports
This endpoint allows for creating a new export job.
Parameters
Section titled ParametersThese 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
Section titled Request example 1curl --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}'
Request example 2
Section titled Request example 2curl --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}'
Response example
Section titled Response example{ "payload": { "jobId": 1372 }, "success": true}
Get the list of all export jobs
Section titled Get the list of all export jobsGET /v1/exports
This endpoint provides the list of all the available export jobs (be they in status active, suspended, computing or completed).
Parameters
Section titled Parametersformat (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
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exports?state=completed' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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
Section titled Get the list of all successful job runsGET /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
Section titled Parameterslimit (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
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exports/successful-runs' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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": "JSONL", "scope": "views", "frequency": "string", "nbOfFiles": 0 } ], "success": true}
Get a specific job
Section titled Get a specific jobGET /v1/exports/{jobId}
This endpoint allows for retrieving a specific job with its ID.
Parameters
Section titled ParametersNone.
Request example
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exports/1234' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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": "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 jobGET /v1/exports/{jobId}/runs
This endpoint provides the list of all the job runs related to a specific job.
Parameters
Section titled Parameterslimit (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
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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
Section titled Get a specific job runGET /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
Section titled ParametersNone.
Request example
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs/67226' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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
Section titled Get the list of all exportable fieldsGET /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
Section titled Parametersscope (string) | Required. To filter based on the job scope (see Enumerations) |
---|
Request example
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/exportable-fields?scope=sessions' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled Response example{ "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 variablesGET /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
Section titled ParametersNo Parameters
Request example
Section titled Request examplecurl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \--header 'Authorization: Bearer <your_access_token>'
Response example
Section titled 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
Section titled Get the list of dynamic variablesGET /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
Section titled Parametersfrom | 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
Section titled Request examplecurl --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>'
Response example
Section titled 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}