Endpoints reference

Last updated Sep 9, 2026View as Markdown

The Data Export API provides endpoints to create and manage export jobs, list job runs, and download extraction files.

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 represent the next date range that will be extracted, while lastRunTime and nextRunTime indicate 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 represent the next date range that will be extracted, while lastRunTime and nextRunTime indicate 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.

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
}