Endpoints reference

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.

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

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

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

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

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.

Path parameters

• jobId   integer   Required

  The Job ID.

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

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.

Path parameters

• jobId   integer   Required

  The Job ID.

• runId   integer   Required

  The Job Run ID.

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

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

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

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
}