# 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="/pages/qhwaMg7tYInVyP5lbRoS" %}
[Raw Data](/cbp/api/headline-testing-api/raw-data.md)
{% endcontent-ref %}

{% content-ref url="/pages/Fa2sByAYYwRvGL0ooWHK" %}
[Summary Report](/cbp/api/headline-testing-api/summary-report.md)
{% endcontent-ref %}

{% content-ref url="/pages/wJ1lF6K6xJTOY6uARGQa" %}
[Variant Report](/cbp/api/headline-testing-api/variant-report.md)
{% endcontent-ref %}


---

# 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://docs.chartbeat.com/cbp/api/headline-testing-api/getting-started-with-our-headline-testing-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.