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
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)
traffic_rank
int (optional)
Filters search to only sites based on percentile monthly traffic.
Example:
95 will filter results to top 5% of news sites.
Response
query_id
string
state
string
Query success or fail
Get results
POST /api/v2/get-results
End-point for retrieving query results fom Athena News API.
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
totalResults
int
Number of results
articles
array (optional)
state
date (optional)
Query success, fail, or pending
Submit a query
POST /api/v2/query
End-point for querying Athena news database. Works best with smaller time-frame queries (7 day time frame)
Headers
Content-Type
application/json
Body
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)
traffic_rank
int (optional)
Filters search to only sites based on percentile monthly traffic.
Example:
95 will filter results to top 5% of news sites.
Response
results
dict
state
date
Query success or fail
Last updated