Endpoints reference

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:

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

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

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

Parameters

None.

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.

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

Parameters

None.

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

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 this documentation

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