> 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/getting-started/api-reference/news-search.md).

# News Search

## 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                                                                                                                                                |
| `key_phrases`  | string (optional)                  | Key phrases to refine articles results                                                                                                                      |
| `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/getting-started/supported-languages.md)                                                            |
| `sort_order`   | string (optional)                  | "Relevance" or "Date Published". Defaults to "Relevance".                                                                                                   |
| `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/getting-started/data-model-reference/articles.md) |
| `state`        | date (optional)  | Query success, fail, or pending                                                   |