---
title: "Submit a Bulk Scores Request"
method: POST
path: "/scores/bulk"
tags: ["Data"]
---

# Submit a Bulk Scores Request

`POST /scores/bulk`

## Request

- Base URL: `https://api.morningconsult.com/v1`
- URL: `https://api.morningconsult.com/v1/scores/bulk`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/morningconsult/apis/morning-consult-api/docs/scores/bulk/post.ts> (a function with typed inputs; its response is checked against the schema)

Submit a request to asynchronously generate timeseries score data for one or more named scores and audiences from the specified data source. The max date range for a single request is 10 years. Returns a `request_id` that can be used to poll the status of the report via the [/scores/bulk/{request_id}](#GET-getScoresBulkStatus) endpoint. When the report is complete, a download URL will be provided to retrieve the data.

## Request body

- PostScoresBulkInput
  - `data_source_id` string, uuid, required: The unique identifier for a data source.
  - `country` string, required: 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.
  - `scores` object, required: 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.
  - `audiences` object: 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.
  - `min_date` string, date: 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.
  - `max_date` string, date: 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.
  - `aggregation` 'day' | 'week' | 'month' | 'quarter' | 'year', required: 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. Each 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.

## Response `200`

Bulk Scores Request Submitted

- PostScoresBulkOutput
  - `request_id` string, uuid: 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.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error

---

[API](https://skmtc.dev/morningconsult/apis/morning-consult-api.md) - [All operations](https://skmtc.dev/morningconsult/apis/morning-consult-api/llms.txt) - [OpenAPI document](https://skmtc.dev/morningconsult/apis/morning-consult-api/revisions/70d621a9c59c?raw)