> For the complete documentation index, see [llms.txt](https://athena-10.gitbook.io/athena-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://athena-10.gitbook.io/athena-api/athena-api-v2/getting-started/api-reference/news-search.md).

# News Search

For news searches, we recommend using `/api/v2/query-async`, which lets you submit a query and retrieve the results later via `/api/v2/get-results`, making it well-suited for larger queries spanning extended timeframes. For shorter timeframes, such as one or two days, the `/api/v2/query` method is a more suitable option.

## Submit a async query

`POST /api/v2/query-async`

Primary end-point for query Athena news database. Used in conjunction with `/api/v2/get-results.`

**Body**

| Name           | Type                               | Description                                                                                                                                                 |
| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`        | string (required)                  | Query string                                                                                                                                                |
| `api_key`      | string (required)                  | Your Athena API key.                                                                                                                                        |
| `sites`        | array (optional)                   | Array of strings \["cnn.com","nytimes.com"]                                                                                                                 |
| `start_date`   | date (optional)                    | Date in ISO 8601 format                                                                                                                                     |
| `end_date`     | date (optional)                    | Date in ISO 8601 format                                                                                                                                     |
| `toggle_state` | string (optional)                  | All Articles or Encoded Articles                                                                                                                            |
| `embeddings`   | boolean (optional \[true / false]) | Returns embeddings with articles                                                                                                                            |
| `page`         | int (required)                     | Page to iterate through results                                                                                                                             |
| `language`     | string (optional)                  | Defaults to 'all'. See [supported languages](/athena-api/athena-api-v2/getting-started/supported-languages.md)                                              |
| `traffic_rank` | int (optional)                     | <p>Filters search to only sites based on percentile monthly traffic. <br></p><p><em>Example:</em></p><p>95 will filter results to top 5% of news sites.</p> |

**Response**

<table><thead><tr><th width="214">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>query_id</code></td><td>string</td><td>Used for querying job status and retrieving results from <a href="#get-results">/api/v2/get-results</a></td></tr><tr><td><code>state</code></td><td>string</td><td>Query success or fail</td></tr></tbody></table>

## Get results

<mark style="color:green;">`POST`</mark> `/api/v2/get-results`

End-point for retrieving query results fom Athena News API.

| Name       | Type              | Description                                                                         |
| ---------- | ----------------- | ----------------------------------------------------------------------------------- |
| `query_id` | string (required) | Use the query id issued in response to submitting your query to /api/v2/query-async |
| `api_key`  | string (required) | Your Athena API key.                                                                |
| `page`     | int (optional)    | Defaults to first page of results unless otherwise specified                        |

**Response**

| Name           | Type             | Description                                                                                     |
| -------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `totalResults` | int              | Number of results                                                                               |
| `articles`     | array (optional) | Array of [articles](/athena-api/athena-api-v2/getting-started/data-model-reference/articles.md) |
| `state`        | date (optional)  | Query success, fail, or pending                                                                 |

## Submit a query

<mark style="color:green;">`POST`</mark> `/api/v2/query`

End-point for querying Athena news database. Works best with smaller time-frame queries (7 day time frame)

**Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

**Body**

| Name           | Type                               | Description                                                                                                                                                 |
| -------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query`        | string (required)                  | Query string                                                                                                                                                |
| `api_key`      | string (required)                  | Your Athena API key.                                                                                                                                        |
| `sites`        | array (optional)                   | Array of strings \["cnn.com","nytimes.com"]                                                                                                                 |
| `start_date`   | date (optional)                    | Date in ISO 8601 format                                                                                                                                     |
| `end_date`     | date (optional)                    | Date in ISO 8601 format                                                                                                                                     |
| `toggle_state` | string (optional)                  | All Articles or Encoded Articles                                                                                                                            |
| `embeddings`   | boolean (optional \[true / false]) | Returns embeddings with articles                                                                                                                            |
| `page`         | int (required)                     | Page to iterate through results                                                                                                                             |
| `language`     | string (optional)                  | defaults to 'all'. See [supported languages](/athena-api/athena-api-v2/getting-started/supported-languages.md)                                              |
| `traffic_rank` | int (optional)                     | <p>Filters search to only sites based on percentile monthly traffic. <br></p><p><em>Example:</em></p><p>95 will filter results to top 5% of news sites.</p> |

**Response**

| Name      | Type | Description                                                                                                                           |
| --------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `results` | dict | Contains total articles (int) and an array of [articles](/athena-api/athena-api-v2/getting-started/data-model-reference/articles.md). |
| `state`   | date | Query success or fail                                                                                                                 |