Endpoints reference

Create an export job

POST /v1/exports

This endpoint allows for creating a new export job.

Request parameters

name string Required

The name of the export. Must not be empty.
format string Required

The file format of the export output.
Possible values: JSONL, or CSV.
scope string (<= 255 chars)

The scope of the export.
frequency object Required

The frequency of the export.

value string

The frequency value.
Possible values: once, daily, or hourly.

dateRange.from string

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

dateRange.to string

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 object Required

The list of fields to export.
To list the exportable fields for a given scope, see the dedicated endpoint.

fieldName string 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, except for the special values custom_var and dynamic_var (used to export custom or dynamic variables).

aliasName string

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

customVarPosition string

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 Sending custom vars. To list custom variables available on the authenticated project, see the /v1/custom_vars endpoint.

dynamicVarKey string

Required only if dynamic_var is specified as fieldName. The dynamic variable key. To learn more about dynamic variables, see Sending dynamic vars. To list dynamic variables available on the authenticated project, see the /v1/dynamic_var_keys endpoint.
deviceLabel string Required

A device filter.
Possible values: all, desktop, mobile, or tablet.
segmentId string

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.

Request example 1

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
}'

Request example 2

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
}'

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

Query parameters

format string

To filter based on the export format (see Enumerations)
frequency string

To filter based on the export frequency (see Enumerations)
limit integer

To change the page size of results (25 by default, 100 max).
order string

To change the order of the results list (“ASC” or “DESC”, “DESC” by default).
Ordering is based on the jobId.
page integer

The page of results to retrieve.
scope string

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

To filter based on the job status (see Enumerations)

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/exports?state=completed' \
--header 'Authorization: Bearer <your_access_token>'

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. Use it to find which jobs have generated extraction files to be downloaded.

Query parameters

page integer

The page of results to retrieve.
order string

To change the order of the results list (“ASC” or “DESC”, “DESC” by default).
Ordering is based on the jobId.
limit integer

To change the page size of results (25 by default, 100 max).

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/exports/successful-runs' \
--header 'Authorization: Bearer <your_access_token>'

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

GET /v1/exports/{jobId}

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

Path parameters

jobId integer Required

The Job ID.

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/exports/1234' \
--header 'Authorization: Bearer <your_access_token>'

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

GET /v1/exports/{jobId}/runs

This endpoint provides the list of all the job runs related to a specific job.

Path parameters

jobId integer Required

The Job ID.

Query parameters

limit integer

To change the page size of results (25 by default, 100 max).
order string

To change the order of the results list (“ASC” or “DESC”, “DESC” by default).
Ordering is based on the jobId.
page integer

The page of results to retrieve.
state string

To filter based on the job status (see Enumerations).

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs' \
--header 'Authorization: Bearer <your_access_token>'

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.

Path parameters

jobId integer Required

The Job ID.
runId integer Required

The Job Run ID.

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/exports/1354/runs/67226' \
--header 'Authorization: Bearer <your_access_token>'

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

Query 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 <your_access_token>'

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 Sending custom vars.

Parameters

No parameters.

Request example

curl --location --request GET 'https://api.contentsquare.com/v1/custom-vars' \
--header 'Authorization: Bearer <your_access_token>'

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 dynamic variables, see Sending dynamic variables.

Query parameters

from ISO 8601 date string

Start date of the query date range.
to ISO 8601 date string

End date of the query date range.

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 <your_access_token>'

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
}

Create an export job

Request parameters

name string Required

format string Required

scope string (<= 255 chars)

frequency object Required

value string

dateRange.from string

dateRange.to string

fields object Required

fieldName string Required

aliasName string

customVarPosition string

dynamicVarKey string

deviceLabel string Required

segmentId string

Request example 1

Request example 2

Response example

Get the list of all export jobs

Query parameters

format string

frequency string

limit integer

order string

page integer

scope string

state string

Request example

Response example

Get the list of all successful job runs

Query parameters

page integer

order string

limit integer

Request example

Response example

Get a specific job

Path parameters

jobId integer Required

Request example

Response example

Get the list of all job runs of a job

Path parameters

jobId integer Required

Query parameters

limit integer

order string

page integer

state string

Request example

Response example

Get a specific job run

Path parameters

jobId integer Required

runId integer Required

Request example

Response example

Get the list of all exportable fields

Query parameters

scope string Required

Request example

Response example

Get the list of custom variables

Parameters

Request example

Response example

Get the list of dynamic variables

Query parameters

from ISO 8601 date string

to ISO 8601 date string

Request example

Response example