GET /api/v1/study

Retrieves a list of studies that were updated after the specified date.

Request path parameters

The following table lists the GET /api/v1/study request path parameters.

Property Required? Value Type Description
updateAfter Required Integer (int64) The Unix timestamp (in seconds) of the day after the last update of the studies you want to retrieve. For example, if you want to retrieve all studies that were last updated after October 31, 2024, 11:59:59 PM UTC, specify the date and time as 1730419199.
pageSize Optional Integer (int32) The number of results per page. The default value is 20.
pageNumber Optional Integer (int32) The number of the current page to return. The default value is 1.

Response example

A successful response returns a list of studies that were updated after the date you specified.

{
  "totalCount": 1,
  "pageSize": 20,
  "pageNumber": 0,
  "studies": [
    {
      "providerId": "thetradedesk",
      "templateKey": "bls-awareness",
      "studyId": "00000000-0000-0000-0000-000000000001",
      "studyName": "The name of the brand lift study",
      "studyStatus": "Ready",
      "country": "US",
      "language": "en",
      "industry": "Retail",
      "startTime": "2024-03-01T00:00:00.000Z",
      "endTime": "2024-04-01T00:00:00.000Z",
      "lastUpdateTime": "2024-02-01T10:01:30.359Z",
      "version": 1675245690,
      "estimatedNextReportUpdateUtc": "2024-12-19T04:37:45.493Z",
      "errorMessage": null,
      "targeting": {
        "age": ["18+", "65+"],
        "gender": ["non-binary"],
        "city": ["CITY_NAME_PLACEHOLDER"],
        "region": ["REGION_NAME_PLACEHOLDER"],
        "CUSTOM_TARGETING_FIELD_PLACEHOLDER": [
          "TARGETING_VALUE_PLACEHOLDER_01",
          "TARGETING_VALUE_PLACEHOLDER_02"
        ]
      },
      "targetBrand": "AdvertiserBrand",
      "competitors": ["CompetingBrandA", "CompetingBrandB"],
      "questions": [
        {
          "questionKey": "brand-preference",
          "questionText": "Which of the following brands do you most prefer?",
          "questionType": "SingleSelect",
          "questionOrder": 1,
          "attachmentId": "97e28a16-b0c0-4d49-811d-843aec85acc1",
          "isAnswerRandomOrdered": true,
          "answers": [
            {
              "answerText": "AdvertiserBrand",
              "answerOrder": 1,
              "isInTarget": true,
              "isAnchored": false
            },
            {
              "answerText": "CompetingBrandA",
              "answerOrder": 2,
              "isInTarget": false,
              "isAnchored": false
            },
            {
              "answerText": "CompetingBrandB",
              "answerOrder": 3,
              "isInTarget": false,
              "isAnchored": false
            },
            {
              "answerText": "None of the above",
              "answerOrder": 3,
              "isInTarget": false,
              "isAnchored": true
            }
          ]
        }
      ],
      "SEGMENT_ID_PLACEHOLDER": "a1b2c3",
      "CUSTOM_FIELD_01_PLACEHOLDER": "VALUE_PLACEHOLDER_01",
      "CUSTOM_FIELD_02_PLACEHOLDER": "VALUE_PLACEHOLDER_02"
    }
  ]
}

Error codes and messages

The following table provides a list of common errors and their respective HTTP error codes.

HTTP Code Status Description
400 Bad Request The query is invalid.