# 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                                                   |


---

# 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://athena-10.gitbook.io/athena-api/getting-started/api-reference/news-search.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.