# Downloading bulk data via API

Ballotpedia’s bulk data clients can access their data on-demand with our client portal at [https://clients.ballotpedia.org/](https://clients.ballotpedia.org/login). The data is refreshed every 24 hours. You may access your data through two methods, as described below:

1. Login with provided password and click to download latest file (for non-technical users)
2. Access latest data file via API (for technical users, [*see next page*](/downloading-bulk-data-via-api.md))

## API instructions

{% hint style="info" %}
Contact Ballotpedia’s data sales staff to request such a key.
{% endhint %}

The API can be called directly by interacting with two endpoints. Please note that these endpoints can only be accessed from a non-CORS context.

```
GET https://api.ballotpedia.org/getQueryList
```

[<br>](https://api.ballotpedia.org/getQueryList)This endpoint will return an array of objects, each object represents a data set and contains the ID, Title and Description.

The endpoint requires your API Key passed in as a header:

```
x-api-key: [your api key]
```

### Examples

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXeU_i6sQvmgN11dVjPMxTylLk7CZycoUOtFibX9lUCp4CyDZEXVyEGk8ImHAnMKJeYCBC2S1sRJVZ42FGjMf1OqTgKypjY5G1KBWNTXNNWsPSfHaHa44i-4vtwvECAYRAtEvqThgCVQ5RDG6UYXL6qCbZnc?key=WeVmNTzl4NMpWbwiYrf2-w" alt=""><figcaption><p>Example call using Postman</p></figcaption></figure>

Example response with a single file:

{% code overflow="wrap" %}

```
{"success":true,"data":[{"id":"1098","title":"Endorsements Sample for Data Clients","description":"List endorsements for 2020 candidates"}],"message":null}
```

{% endcode %}

This endpoint will return a URL to the requested file:

```
POST https://api.ballotpedia.org/getQueryResults
```

The endpoint requires your API Key passed in the header as described above, the content type of application/json, and the ID (obtained from the getQueryList endpoint) of the data set and the format passed via the body in the POST request.

\
**Headers**

```
x-api-key: [your api key]
Content-Type: application/json
```

**Body**

```
{
  "id": "1098",
  "format": "json"
}
```

To get the data to return in csv format, make the same call as for json data but change the format parameter from json to csv.

```
{
  "id": "1098",
  "format": "csv"
}
```

<figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcPc_tJpL0jI9tWmPrNZAyGvnvrQXtlfHI8BjJ7LCoPHU99CT0gNcKpMtpBrNKmyA-kHpGcIPW7QuoAph4_tccxarmmjNPPhTmxO2k-f6fU3NdGwRHGP2PFo7P-c4gcnX8UjjD-NbCzYuidQIUYJ4l4BU9l?key=WeVmNTzl4NMpWbwiYrf2-w" alt=""><figcaption><p>Example call using Postman</p></figcaption></figure>

\
Example Response:

{% code overflow="wrap" %}

```
{"success":true,"data":{"url":"https://ballotpedia-data-clients.s3.amazonaws.com/metabase_query_results_1253.json?AWSAccessKeyId=XXXXXXXXXXXXXXX&Expires=XXXXXXX&Signature=XXXXXXXX"},"message":"Success"}
```

{% endcode %}

{% hint style="warning" %}
The URL for the downloadable file expires after 5 minutes. The URL returned should change with each call to getQueryResults. Files are re-generated daily, and the URL will always return only the last generated file.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.ballotpedia.org/downloading-bulk-data-via-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.