{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/morning-consult/refs/heads/main/json-schema/morning-consult-schemas.json",
  "title": "Morning Consult API schemas",
  "description": "JSON Schema derived verbatim from components.schemas of the Morning Consult OpenAPI 3.0.3 document at https://api.morningconsult.com/openapi.yaml. Internal $ref pointers were rewritten from #/components/schemas/ to #/$defs/; no schema content was altered.",
  "x-generated": "2026-08-01",
  "x-method": "derived",
  "x-source": "openapi/morning-consult-openapi-original.yml",
  "$defs": {
    "PaginationToken": {
      "type": "string",
      "format": "base64",
      "description": "A pagination token to use to get paginated results. For more details, see the section on [Pagination](#pagination).",
      "pattern": "^(?:[A-Za-z\\d+/]{4})*(?:[A-Za-z\\d+/]{3}=|[A-Za-z\\d+/]{2}==)?$",
      "minLength": 3,
      "maxLength": 300,
      "example": "eyJxdWVyeSI6ImRvZ3MifQ=="
    },
    "Error": {
      "type": "object",
      "description": "Error message.",
      "additionalProperties": false,
      "example": {
        "code": 500,
        "status": "Internal Server Error",
        "errors": [
          "Oops, something went wrong"
        ]
      },
      "properties": {
        "code": {
          "type": "integer",
          "description": "Numeric HTTP status code.",
          "example": 500,
          "format": "int32",
          "minimum": 100,
          "maximum": 599
        },
        "status": {
          "type": "string",
          "description": "Text description of HTTP status code.",
          "example": "Internal Server Error"
        },
        "errors": {
          "type": "array",
          "description": "Messages describing errors.",
          "items": {
            "title": "error",
            "type": "string",
            "description": "A specific error message."
          },
          "example": [
            "Oops, something went wrong"
          ]
        }
      }
    },
    "Entity": {
      "title": "Entity",
      "type": "object",
      "description": "A particular subject to which a question may refer, such as a specific brand or politician.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the entity, which can be used for filtering questions."
        },
        "label": {
          "type": "string",
          "description": "The descriptive label of the entity, usually the name."
        }
      },
      "example": {
        "id": "autotrader",
        "label": "Autotrader"
      }
    },
    "EntityType": {
      "title": "EntityType",
      "description": "A entity type, such as brand or favorability.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the entity type, which can be used for filtering entities."
        },
        "label": {
          "type": "string",
          "description": "The descriptive label of the entity type."
        }
      },
      "example": {
        "id": "favorability",
        "label": "Favorability"
      }
    },
    "Category": {
      "title": "Category",
      "type": "object",
      "description": "A type of question.",
      "properties": {
        "id": {
          "type": "string",
          "description": "The ID of the category, which can be used for filtering questions and entities."
        },
        "label": {
          "type": "string",
          "description": "The descriptive label for the category."
        }
      },
      "example": {
        "id": "brand",
        "label": "Brand"
      }
    },
    "CountryCode": {
      "title": "CountryCode",
      "description": "Two letter [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code. This can be used in the `country_code` query parameter of multiple endpoints to limit results to the specific country.",
      "type": "string",
      "example": "us",
      "pattern": "^[a-z]+",
      "minLength": 2,
      "maxLength": 2
    },
    "Country": {
      "title": "Country",
      "type": "object",
      "properties": {
        "code": {
          "$ref": "#/$defs/CountryCode"
        },
        "label": {
          "type": "string",
          "description": "The full name for the country."
        }
      },
      "example": {
        "code": "us",
        "label": "United States"
      },
      "description": "A country."
    },
    "DataSource": {
      "title": "Data Source",
      "type": "object",
      "description": "A data source and the countries it supports.",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the data source.",
          "example": "00de2081-e013-411d-823c-cd483283e38d"
        },
        "name": {
          "type": "string",
          "description": "The human-readable name of the data source.",
          "example": "Daily Tracker"
        },
        "countries": {
          "type": "array",
          "description": "The countries the score is available in for this data source.",
          "items": {
            "$ref": "#/$defs/Country"
          }
        }
      }
    },
    "ScoreID": {
      "title": "Score ID",
      "description": "The unique identifier for a score.",
      "type": "string",
      "format": "uuid",
      "example": "7fa7d4a5-8b79-462c-b9ae-03a0431cb5e5"
    },
    "Score": {
      "title": "Score",
      "description": "The representation of a score and its relevant metadata. If entity type is present, then an entity that satisfies the entity type must be passed into [/surveys/syndicated/scores](#POST-postSurveysSyndicatedScores). If `components` is present, at least one component ID must be supplied in `component_ids` when running the score.",
      "type": "object",
      "example": {
        "id": "7fa7d4a5-8b79-462c-b9ae-03a0431cb5e5",
        "label": "Avon Favorability"
      },
      "properties": {
        "id": {
          "$ref": "#/$defs/ScoreID"
        },
        "label": {
          "type": "string",
          "description": "A short label describing the score."
        },
        "description": {
          "type": "string",
          "description": "A description of the score."
        },
        "entity_type": {
          "$ref": "#/$defs/EntityType"
        },
        "components": {
          "type": "array",
          "description": "The components available for this score. Scores such as \"Price Surprise\" and \"Unavailability\" expose components that restrict the calculation to a subset of categories (for example \"home_appliances\"). If this field is present, at least one component ID must be provided in `component_ids` when running the score.",
          "items": {
            "type": "object",
            "description": "A component available for this score.",
            "properties": {
              "id": {
                "type": "string",
                "description": "The unique identifier for the component.",
                "example": "home_appliances"
              }
            },
            "required": [
              "id"
            ]
          }
        }
      }
    },
    "ResponseID": {
      "title": "ResponseID",
      "type": "string",
      "pattern": "^[0-9]+$",
      "minLength": 0,
      "maxLength": 100,
      "description": "Unique identifier for a question response. Response IDs are only unique within a question, and not across them.",
      "example": "1"
    },
    "ResponseLabel": {
      "title": "ResponseLabel",
      "type": "string",
      "description": "The full textual label for the response, as selected by a respondent.",
      "example": "Very Favorable"
    },
    "Responses": {
      "type": "array",
      "description": "The response IDs and labels for the question.",
      "items": {
        "$ref": "#/$defs/Response"
      }
    },
    "Response": {
      "title": "response",
      "type": "object",
      "description": "A single response option for a question.",
      "example": {
        "id": "1",
        "label": "Several times a day"
      },
      "properties": {
        "id": {
          "$ref": "#/$defs/ResponseID"
        },
        "label": {
          "$ref": "#/$defs/ResponseLabel"
        }
      }
    },
    "QuestionID": {
      "title": "Question ID",
      "description": "The unique identifier for a question.",
      "type": "string",
      "format": "uuid",
      "example": "a7ee637c-e5d1-4cf8-b484-8eb372f22941"
    },
    "DataSourceID": {
      "title": "Data Source ID",
      "description": "The unique identifier for a data source.",
      "type": "string",
      "format": "uuid",
      "example": "00de2081-e013-411d-823c-cd483283e38d"
    },
    "Question": {
      "title": "Question",
      "description": "The representation of a survey question and its relevant metadata.",
      "type": "object",
      "example": {
        "id": "cbaad021-12b7-5cd2-9a0f-3ed556946d0d",
        "label": "Avon Usage Frequency",
        "text": "How often do you use or purchase something from the following? --- Avon",
        "country": {
          "code": "fr",
          "label": "France"
        },
        "category": {
          "id": "brand",
          "label": "Brand"
        },
        "responses": [
          {
            "id": "1",
            "label": "Several times a day"
          },
          {
            "id": "2",
            "label": "About once a day"
          },
          {
            "id": "3",
            "label": "A few times a week"
          },
          {
            "id": "4",
            "label": "About once a week"
          },
          {
            "id": "5",
            "label": "About once a month or less often"
          },
          {
            "id": "6",
            "label": "I do not have an account or do not use"
          }
        ],
        "entity": {
          "id": "avon",
          "label": "Avon"
        }
      },
      "properties": {
        "id": {
          "$ref": "#/$defs/QuestionID"
        },
        "label": {
          "type": "string",
          "description": "A short label describing the question."
        },
        "text": {
          "type": "string",
          "description": "The full text of the question, as shown to respondents. For questions that we do not ask directly, such as certain demographic questions, this field will be omitted."
        },
        "country": {
          "$ref": "#/$defs/Country"
        },
        "category": {
          "$ref": "#/$defs/Category"
        },
        "responses": {
          "$ref": "#/$defs/Responses"
        },
        "entity": {
          "$ref": "#/$defs/Entity"
        }
      }
    },
    "DataSourceQuestion": {
      "title": "Data Source Question",
      "description": "A question across accessible data sources.",
      "type": "object",
      "required": [
        "id",
        "label",
        "country",
        "data_source_id"
      ],
      "example": {
        "id": "cbaad021-12b7-5cd2-9a0f-3ed556946d0d",
        "label": "Avon Usage Frequency",
        "text": "How often do you use or purchase something from the following? --- Avon",
        "data_source_id": "00de2081-e013-411d-823c-cd483283e38d",
        "country": {
          "code": "fr",
          "label": "France"
        },
        "category": {
          "id": "brand",
          "label": "Brand"
        },
        "responses": [
          {
            "id": "1",
            "label": "Several times a day"
          },
          {
            "id": "2",
            "label": "About once a day"
          },
          {
            "id": "3",
            "label": "A few times a week"
          },
          {
            "id": "4",
            "label": "About once a week"
          },
          {
            "id": "5",
            "label": "About once a month or less often"
          },
          {
            "id": "6",
            "label": "I do not have an account or do not use"
          }
        ],
        "entity": {
          "id": "avon",
          "label": "Avon"
        }
      },
      "properties": {
        "id": {
          "$ref": "#/$defs/QuestionID"
        },
        "label": {
          "type": "string",
          "description": "A short label describing the question."
        },
        "text": {
          "type": "string",
          "description": "The full text of the question, as shown to respondents. For questions that we do not ask directly, such as certain demographic questions, this field will be omitted."
        },
        "data_source_id": {
          "$ref": "#/$defs/DataSourceID"
        },
        "country": {
          "$ref": "#/$defs/Country"
        },
        "category": {
          "$ref": "#/$defs/Category"
        },
        "responses": {
          "$ref": "#/$defs/Responses"
        },
        "entity": {
          "$ref": "#/$defs/Entity"
        }
      }
    },
    "MaxDate": {
      "type": "string",
      "format": "date",
      "description": "Maximum date of data returned in YYYY-MM-DD format. The date provided is inclusive. Omitting this field will return the most recent available trend data.",
      "example": "2018-01-31",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
      "minLength": 10,
      "maxLength": 10
    },
    "MinDate": {
      "type": "string",
      "format": "date",
      "description": "Minimum date of data returned in YYYY-MM-DD format. The date provided is inclusive. Omitting this field will return the earliest available trend data.",
      "example": "2018-01-31",
      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
      "minLength": 10,
      "maxLength": 10
    },
    "Audience": {
      "title": "Audience",
      "type": "object",
      "description": "The description of respondents considered in a request. Data in the response will be filtered to only include respondents who match the audience described in this parameter.\nThe `match` field specifies respondents that selected one or more particular response options for a question. The `and`, `or`, and `not` fields allow Boolean logic to be applied to matches. These logic fields can be nested as necessary to create audiences. See <a class=\"text-break\" href=\"#sample-workflow-building-a-custom-audience\">Workflow: Building a Custom Audience</a> for an example.\nThe maximum number of conditions that can be used to build an audience in a single request is 20. This includes all nested conditions within `and`, `or`, and `not` fields.",
      "oneOf": [
        {
          "$ref": "#/$defs/AudienceMatch"
        },
        {
          "type": "array",
          "title": "and",
          "description": "A list of audience definitions of which all must match.",
          "items": {
            "$ref": "#/$defs/Audience"
          }
        },
        {
          "type": "array",
          "title": "or",
          "description": "A list of audience definitions of which at least one must match.",
          "items": {
            "$ref": "#/$defs/Audience"
          }
        },
        {
          "type": "object",
          "title": "not",
          "description": "A list of audience definitions of which none must match.",
          "allOf": [
            {
              "$ref": "#/$defs/Audience"
            }
          ]
        }
      ]
    },
    "AudienceMatch": {
      "type": "object",
      "title": "match",
      "description": "A question ID and the valid responses for that question. The `response_ids` are a list of IDs which the question must match one of in order for the response to be included in the final aggregation.",
      "example": {
        "question_id": "29433f2b-3ea0-4214-ae8f-9ad09549c082",
        "response_ids": [
          "1",
          "2"
        ]
      },
      "properties": {
        "question_id": {
          "$ref": "#/$defs/QuestionID"
        },
        "response_ids": {
          "type": "array",
          "description": "The list of IDs which the question must match one of.\nResponse IDs can be found from the [/surveys/syndicated/questions](#GET-getSurveysSyndicatedQuestions) and [/surveys/syndicated/questions/{question_id}](#GET-getSurveysSyndicatedQuestionsByID) endpoints under the `responses[]` array.",
          "minItems": 1,
          "maxItems": 100,
          "uniqueItems": true,
          "items": {
            "$ref": "#/$defs/ResponseID"
          }
        }
      },
      "required": [
        "question_id",
        "response_ids"
      ]
    },
    "Aggregation": {
      "title": "Aggregation",
      "type": "object",
      "description": "Options for aggregating data. For calendar durations, sample for that duration will be aggregated into a single data point. For example, requesting data between \"2018-01-01\" and \"2018-12-31\" with the month interval will return a data point for each month.\nEach data point representing an interval will be timestamped with the start date of that interval. The \"week\" interval starts on Monday, and the \"all\" option will return a single data point aggregating all trend data.",
      "example": {
        "interval": "month"
      },
      "properties": {
        "interval": {
          "type": "string",
          "description": "Interval to aggregate the data.",
          "enum": [
            "day",
            "week",
            "month",
            "quarter",
            "year",
            "all"
          ],
          "example": "month"
        }
      },
      "required": [
        "interval"
      ]
    },
    "BulkAggregation": {
      "title": "BulkAggregation",
      "type": "string",
      "description": "Options for aggregating data. For calendar durations, sample for that duration will be aggregated into a single data point. For example, requesting data between \"2018-01-01\" and \"2018-12-31\" with the month interval will return a data point for each month.\nEach data point representing an interval will be timestamped with the start date of that interval. The \"week\" interval starts on Monday, and the \"all\" option will return a single data point aggregating all trend data.",
      "enum": [
        "day",
        "week",
        "month",
        "quarter",
        "year"
      ],
      "example": "month"
    },
    "ScoreDataPoint": {
      "title": "Score Data Point",
      "type": "object",
      "description": "Data point associated with a score.",
      "example": {
        "date": "2025-11-14",
        "score": {
          "value": 43
        },
        "total_n": 1550
      },
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "Date of the sample in YYYY-MM-DD format. For interval aggregations, this date represents the start date of that interval.",
          "example": "2019-08-13",
          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
          "minLength": 10,
          "maxLength": 10
        },
        "score": {
          "$ref": "#/$defs/ScoreDataPointValue"
        },
        "total_n": {
          "type": "number",
          "format": "double",
          "description": "Weighted number of respondents for this data point.",
          "minimum": 0
        }
      }
    },
    "ScoreDataPointValue": {
      "title": "Score Data Point Value",
      "type": "object",
      "description": "Data point value associated with a score.",
      "example": {
        "value": 43
      },
      "properties": {
        "value": {
          "type": "number",
          "format": "double",
          "description": "Calculated score."
        }
      }
    },
    "TimeseriesDataPoint": {
      "title": "TimeseriesDataPoint",
      "type": "object",
      "description": "Data point associated with a single survey data trend.",
      "example": {
        "date": "2017-11-23",
        "responses": [
          {
            "percent": 42.953760405946554,
            "id": "1",
            "label": "Very Favorable"
          },
          {
            "percent": 57.046239594053446,
            "id": "2",
            "label": "Somewhat Favorable"
          }
        ],
        "total_n": 1570
      },
      "properties": {
        "date": {
          "type": "string",
          "format": "date",
          "description": "Date of the sample in YYYY-MM-DD format. For interval aggregations, this date represents the start date of that interval.",
          "example": "2019-08-13",
          "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
          "minLength": 10,
          "maxLength": 10
        },
        "total_n": {
          "type": "number",
          "format": "double",
          "description": "Weighted number of respondents for this data point.",
          "minimum": 0
        },
        "responses": {
          "type": "array",
          "description": "Individual data points associated with a specific response.",
          "items": {
            "$ref": "#/$defs/DataPoint"
          }
        }
      }
    },
    "DataPoint": {
      "title": "DataPoint",
      "type": "object",
      "description": "An individual data point representing a particular response.",
      "example": {
        "percent": 42.953760405946554,
        "id": "2",
        "label": "Somewhat Favorable"
      },
      "properties": {
        "id": {
          "$ref": "#/$defs/ResponseID"
        },
        "label": {
          "$ref": "#/$defs/ResponseLabel"
        },
        "percent": {
          "type": "number",
          "format": "double",
          "description": "Numeric representation of the value associated with a response. This is the weighted percentage of respondents who chose the corresponding response to the requested question on the given date, or the date range if aggregated over an interval.",
          "minimum": 0,
          "maximum": 100
        }
      }
    },
    "Tokens": {
      "type": "object",
      "example": {
        "token_type": "Bearer",
        "expires_in": 3600,
        "id_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxM",
        "refresh_token": "eyJxdWVyeSI6ImRvZ3MifQ=="
      },
      "properties": {
        "token_type": {
          "type": "string",
          "description": "The type of token received. Will be Bearer.",
          "example": "Bearer",
          "default": "Bearer"
        },
        "expires_in": {
          "type": "integer",
          "description": "The number of seconds until the token expires.",
          "example": 3600,
          "default": 3600,
          "readOnly": true
        },
        "refresh_token": {
          "type": "string",
          "description": "The refresh token to be used to retrieve a new JWT."
        },
        "id_token": {
          "type": "string",
          "description": "The JWT token. Use this in the Authorization header in requests to other endpoints."
        }
      }
    },
    "PostSurveysSyndicatedScoresInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "audience": {
          "$ref": "#/$defs/Audience"
        },
        "aggregation": {
          "$ref": "#/$defs/Aggregation"
        },
        "score_id": {
          "$ref": "#/$defs/ScoreID"
        },
        "country_code": {
          "$ref": "#/$defs/CountryCode"
        },
        "entity_id": {
          "title": "Entity ID",
          "type": "string",
          "description": "Entity ID to run the score against if an Entity ID is required.",
          "example": "avon"
        }
      },
      "required": [
        "score_id",
        "country_code"
      ]
    },
    "PostScoresInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "data_source_id": {
          "$ref": "#/$defs/DataSourceID"
        },
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "audience": {
          "$ref": "#/$defs/Audience"
        },
        "aggregation": {
          "$ref": "#/$defs/Aggregation"
        },
        "score_id": {
          "$ref": "#/$defs/ScoreID"
        },
        "country_code": {
          "$ref": "#/$defs/CountryCode"
        },
        "entity_id": {
          "title": "Entity ID",
          "type": "string",
          "description": "Entity ID to run the score against if an Entity ID is required.",
          "example": "avon"
        },
        "component_ids": {
          "type": "array",
          "description": "The component IDs to use when computing the score. Required for scores whose metadata lists `components` (for example \"Price Surprise\" and \"Unavailability\"). See [/scores](#GET-getScores) to discover the components available for a score.",
          "items": {
            "type": "string"
          },
          "example": [
            "home_appliances"
          ]
        }
      },
      "required": [
        "data_source_id",
        "score_id",
        "country_code"
      ]
    },
    "PostSurveysSyndicatedTimeseriesInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "audience": {
          "$ref": "#/$defs/Audience"
        },
        "aggregation": {
          "$ref": "#/$defs/Aggregation"
        },
        "question_id": {
          "title": "Question ID",
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for a question.\nThe question itself must have <em>fewer than 100 predefined responses.</em> You can get the number of responses for a question from the <a class=\"text-break\" href=\"#GET-getSurveysSyndicatedQuestionsByID\">/surveys/syndicated/questions/{question_id}</a> endpoint.",
          "example": "a7ee637c-e5d1-4cf8-b484-8eb372f22941"
        }
      },
      "required": [
        "question_id"
      ]
    },
    "PostResponsesInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "data_source_id": {
          "$ref": "#/$defs/DataSourceID"
        },
        "question_id": {
          "$ref": "#/$defs/QuestionID"
        },
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "audience": {
          "$ref": "#/$defs/Audience"
        },
        "aggregation": {
          "$ref": "#/$defs/Aggregation"
        }
      },
      "required": [
        "data_source_id",
        "question_id"
      ]
    },
    "PostAIResolveInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "text": {
          "title": "Text",
          "type": "string",
          "description": "Query text.",
          "minLength": 1,
          "maxLength": 1000,
          "pattern": "^[^\\0]+$",
          "example": "What do women think of Cheerios?"
        }
      },
      "required": [
        "text"
      ]
    },
    "PostSurveysSyndicatedTimeseriesBatchInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "country": {
          "$ref": "#/$defs/CountryCode"
        },
        "question_ids": {
          "type": "array",
          "description": "The unique identifiers for the questions to include in the report.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/QuestionID"
          }
        },
        "audiences": {
          "type": "object",
          "description": "A map of audience names to audience definitions. Each named audience will produce a separate trend in the report output. An empty audience object `{}` represents all respondents. If omitted, the report defaults to a single all-respondents trend.",
          "additionalProperties": {
            "$ref": "#/$defs/Audience"
          }
        },
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "aggregation": {
          "$ref": "#/$defs/BulkAggregation"
        }
      },
      "required": [
        "country",
        "question_ids",
        "aggregation"
      ]
    },
    "PostResponsesBulkInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "data_source_id": {
          "$ref": "#/$defs/DataSourceID"
        },
        "country": {
          "$ref": "#/$defs/CountryCode"
        },
        "question_ids": {
          "type": "array",
          "description": "The unique identifiers for the questions to include in the report.",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/QuestionID"
          }
        },
        "audiences": {
          "type": "object",
          "description": "A map of audience names to audience definitions. Each named audience will produce a separate trend in the report output. An empty audience object `{}` represents all respondents. If omitted, the report defaults to a single all-respondents trend.",
          "additionalProperties": {
            "$ref": "#/$defs/Audience"
          }
        },
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "aggregation": {
          "$ref": "#/$defs/BulkAggregation"
        }
      },
      "required": [
        "data_source_id",
        "country",
        "question_ids",
        "aggregation"
      ]
    },
    "PostResponsesBulkOutput": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the bulk responses request. Use this ID to poll the status of the report via the [/responses/bulk/{request_id}](#GET-getResponsesBulkStatus) endpoint.",
          "example": "b1a2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      }
    },
    "GetResponsesBulkStatusOutput": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the bulk responses request.",
          "example": "b1a2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "status": {
          "type": "string",
          "description": "The current status of the report request.",
          "enum": [
            "processing",
            "complete",
            "error"
          ],
          "example": "complete"
        },
        "download_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to download the completed report. Only present when status is `complete`.",
          "example": "https://example.com/report.parquet"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration time of the download URL. Only present when status is `complete`.",
          "example": "2025-01-01T12:00:00Z"
        }
      }
    },
    "NamedScore": {
      "title": "NamedScore",
      "type": "object",
      "description": "Selection of a single score, optionally bound to a specific entity and subset of components, to include in a bulk scores report.",
      "additionalProperties": false,
      "properties": {
        "score_id": {
          "$ref": "#/$defs/ScoreID"
        },
        "entity_id": {
          "type": "string",
          "description": "Entity ID to run the score against if the score's entity type is set. See [/entities](#GET-getEntities) to discover the entities available for a country and data source.",
          "example": "nike"
        },
        "component_ids": {
          "type": "array",
          "description": "The component IDs to use when computing the score. Required for scores whose metadata lists `components` (for example \"Price Surprise\" and \"Unavailability\"). See [/scores](#GET-getScores) to discover the components available for a score.",
          "items": {
            "type": "string"
          },
          "example": [
            "home_appliances"
          ]
        }
      },
      "required": [
        "score_id"
      ]
    },
    "PostScoresBulkInput": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "data_source_id": {
          "$ref": "#/$defs/DataSourceID"
        },
        "country": {
          "$ref": "#/$defs/CountryCode"
        },
        "scores": {
          "type": "object",
          "description": "A map of caller-defined score names to score selections. Each named score will appear as a separate series in the report output. Score names must be unique within a request.",
          "minProperties": 1,
          "additionalProperties": {
            "$ref": "#/$defs/NamedScore"
          }
        },
        "audiences": {
          "type": "object",
          "description": "A map of audience names to audience definitions. Each named audience will produce a separate series in the report output. An empty audience object `{}` represents all respondents. If omitted, the report defaults to a single all-respondents series.",
          "additionalProperties": {
            "$ref": "#/$defs/Audience"
          }
        },
        "min_date": {
          "$ref": "#/$defs/MinDate"
        },
        "max_date": {
          "$ref": "#/$defs/MaxDate"
        },
        "aggregation": {
          "$ref": "#/$defs/BulkAggregation"
        }
      },
      "required": [
        "data_source_id",
        "country",
        "scores",
        "aggregation"
      ]
    },
    "PostScoresBulkOutput": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the bulk scores request. Use this ID to poll the status of the report via the [/scores/bulk/{request_id}](#GET-getScoresBulkStatus) endpoint.",
          "example": "b1a2c3d4-e5f6-7890-abcd-ef1234567890"
        }
      }
    },
    "GetScoresBulkStatusOutput": {
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid",
          "description": "The unique identifier for the bulk scores request.",
          "example": "b1a2c3d4-e5f6-7890-abcd-ef1234567890"
        },
        "status": {
          "type": "string",
          "description": "The current status of the report request.",
          "enum": [
            "processing",
            "complete",
            "error"
          ],
          "example": "complete"
        },
        "download_url": {
          "type": "string",
          "format": "uri",
          "description": "URL to download the completed report. Only present when status is `complete`.",
          "example": "https://example.com/report.parquet"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time",
          "description": "Expiration time of the download URL. Only present when status is `complete`.",
          "example": "2025-01-01T12:00:00Z"
        }
      }
    }
  }
}