# Getting Started with our Headline Testing API

Our Headline Testing API endpoints can be used to retrieve active and archive headline test data for your site in JSON format programmatically.

{% hint style="info" %}
The API can be accessed by users with "View Only" or "Run Headline Tests" [permissions](https://help.chartbeat.com/hc/en-us/articles/360018183333-Roles-and-permissions-in-Chartbeat) for a site, using an "all" API key.
{% endhint %}

## Required API parameters

**API Key**: To be passed in the HTTP Header with "X-CB-AK". You can create and access your [**API key here**](https://chartbeat.com/publishing/settings/api-keys/) under your account settings. Make sure to select an API key that has access to all calls for your domain. 

### Example CURL request

`curl --header "X-CB-AK: <YOUR API KEY>" "https://api.chartbeat.com/mab/htapi/v1/experiments/raw_data/?host=YOUR_HOST.com&start=2024-01-01&end=2024-01-01&tz=America/New_York&status=active"`

The following parameters are necessary to include in all queries:

| Parameter Name       | Syntax    | Description                                                                                                                      |
| -------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| API Key (*see note*) | `apikey=` | **NOTE**: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](#required-api-parameters) |
| Host                 | `host=`   | The Site you are querying (site ID is usually your website's root domain).                                                       |
| Start Date           | `start=`  | A valid date string in YYYY-MM-DD format.                                                                                        |
| End Date             | `end=`    | A valid date string in YYYY-MM-DD format.                                                                                        |
| Timezone             | `tz=`     | The timezone you'd like to run the query in a valid Olson timezone format, e.g. America/New\_York.                               |

### Optional parameters

Raw data returns comprehensive details about each headline test.

| Parameter Name | Syntax       | Description                                                                                                                                                 |
| -------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Status         | `status=`    | Status of the headline test. Choose from 'active', 'archived', 'all'. Defaults to 'all'. Note that this parameter is only available for raw data endpoint.  |
| Limit          | `limit=`     | The number of rows you'd like to pull in your query. Large calls are susceptible to 504 gateway timeouts, so we recommend setting no more than 10,000 rows. |
| Test Type      | `test_type=` | Chose from "headline","image","headline\_and\_image". Defaults to "all" which includes all 3.                                                               |

## Next steps

Check out the next three pages of this guide to find all the information you need to get started using our Headline Testing API.

{% content-ref url="raw-data" %}
[raw-data](https://docs.chartbeat.com/cbp/api/headline-testing-api/raw-data)
{% endcontent-ref %}

{% content-ref url="summary-report" %}
[summary-report](https://docs.chartbeat.com/cbp/api/headline-testing-api/summary-report)
{% endcontent-ref %}

{% content-ref url="variant-report" %}
[variant-report](https://docs.chartbeat.com/cbp/api/headline-testing-api/variant-report)
{% endcontent-ref %}