We use cookies to ensure you get the best experience on our website. Some of these cookies are provided by third parties. You are free to decide which categories you would like to permit and can withdraw this consent at any time (via cookie preferences link on the footer).
By accepting the necessary cookies, you agree to our privacy policy and terms of service, both located in the footer of the website.
Learn more on our terms of service and privacy policy.
If you are a licensed AskNews publisher, the numbers you see in your publisher dashboard are also available through the API. This page is a set of copy-paste recipes for the questions publishers actually ask:
Everything here uses an organization API key (ank_org_…) — a key created by your organization's owner or admin.
1. Get an organization API key. An owner or admin of your organization creates one in account settings ("Create organization API key"). The key starts with ank_org_ and includes the distribution and news scopes — everything this page needs. Personal API keys cannot access the distribution endpoints.
2. The key only sees your organization's content. Publisher organization keys are limited to the distribution analytics, news search, article lookup, and DeepNews endpoints — always filtered to your organization's domains (DeepNews additionally runs on the AskNews news archive only, not on external sources). Other endpoints return 403.
3. Know your domain names. The API does not expose a "list my domains" endpoint — use the domain names exactly as they appear in your publisher dashboard (for example gbnews.com, not www.gbnews.com).
4. Dates are required, and one request covers one calendar month. start_date and end_date are Unix timestamps in seconds, and both must fall inside the same UTC calendar month. This keeps every query on a single partition of the hits table, which is what makes these endpoints fast. To build a quarterly report, loop month by month and aggregate on your side.
5. These endpoints are rate limited to 0.2 requests/second (short bursts of 5 are allowed) with a maximum of 2 concurrent requests. They are meant for reporting, not for per-page-view lookups. Cache the results on your side; responses are also cached for 30 seconds per key.
| Endpoint | What it answers |
|---|---|
GET /v1/distribution/stats/hit_share | Your share of all publisher traffic in a period |
GET /v1/distribution/articles/top_n_for_domains | Your most-used articles, with hit counts, paginated |
GET /v1/news | Full analytics for your articles, by article_id |
Both distribution endpoints require domain_names, start_date and end_date.
Detailed and updated response structures are always available in the API reference.
stats/hit_share returns your domain's share of all hits across all publisher domains in the period. A value of 0.0058 means your domain accounted for ~0.58% of the publisher traffic AskNews served in that window. You can pass several domains in one call — total_share is the combined share of everything you asked for.
A domain you own that had no traffic in the window comes back with 0.0 rather than being omitted, so you can chart a stable set of series month over month.
articles/top_n_for_domains ranks your articles by hit count — the same "top articles" list as your dashboard. limit is the page size (max 100).
Two things worth knowing about the response:
article_id is the key to everything else. Feed it to /v1/news to get the full article analytics — that is Recipe 4.total_count is the sum of hit_count on the returned page only. It is not the total number of your articles and not your total hits for the month. To total your hits, add up hit_count across every page (see the next recipe).Use page (1-based) with limit as the page size. The response tells you where you are: page echoes the page you fetched, and next_page holds the number of the next one — or null when there is nothing more. Keep requesting while next_page is set.
Notes on paging:
next_page is set whenever a page comes back full, so the last request of a walk may return an empty data array. That is expected — it is how you learn you reached the end.limit above 100 returns 422. Page through instead.The distribution endpoints tell you how much each article was used. /v1/news tells you what the article is: sentiment, topic classification, keywords, entities, reporting voice, page rank, and more. This is exactly how the publisher dashboard builds its articles table — take the article_id values from Recipe 2 or 3 and look them up in batches.
Useful fields for publisher reporting:
| Field | What it gives you |
|---|---|
classification | Topic category — group your hits by subject matter |
keywords, entities | What the article is about, for topic and entity breakdowns |
sentiment | Sentiment score of the article |
reporting_voice | Objective, Analytical, Opinionated, … — style of coverage |
provocative | How provocative the piece is (low/medium/high) |
page_rank | Authority rank of the source at publication time |
key_points | Bullet summary, handy for report exports |
pub_date, language, country | Publication metadata for filtering |
Two practical notes:
/v1/news uses the news scope, which is on your key by default and has its own, more generous rate limit — the 0.2 req/s ceiling only applies to the distribution endpoints.full_text=True if you want the article body along with the analytics.GET /v1/distribution/stats/hit_share| Parameter | Type | Required | Notes |
|---|---|---|---|
domain_names | string (repeatable) | yes | Domains your organization owns |
start_date | integer | yes | Unix seconds, UTC |
end_date | integer | yes | Unix seconds, same UTC month as start_date |
GET /v1/distribution/articles/top_n_for_domains| Parameter | Type | Required | Notes |
|---|---|---|---|
domain_names | string (repeatable) | yes | Domains your organization owns |
start_date | integer | yes | Unix seconds, UTC |
end_date | integer | yes | Unix seconds, same UTC month as start_date |
limit | integer | no | Page size, 1–100, default 10 |
page | integer | no | 1-based page number, default 1 |
GET /v1/news| Parameter | Type | Required | Notes |
|---|---|---|---|
article_ids | UUID (repeatable) | yes | Up to 100 per request |
full_text | boolean | no | Include the article body, default false |
| Status | Code | Meaning | Fix |
|---|---|---|---|
| 403 | 403000 | None of the requested domains belong to your organization, or your key has no distribution scope | Check the domain spelling; create a new key if it predates the distribution scope |
| 422 | 422000 | Missing dates, end_date before start_date, dates spanning two calendar months, or limit above 100 | Split the range by month; page instead of raising limit |
| 429 | — | More than 0.2 requests/second (burst 5) or more than 2 concurrent requests | Add a delay between calls, as in the recipes above |
Why can't I query a full quarter in one call? The hit data is partitioned by month. Restricting each request to a single calendar month is what keeps these queries fast and predictable. Loop over months and aggregate on your side.
Why is total_count smaller than my total hits?
total_count only sums the page you just received. Sum hit_count across all pages for a monthly total.
I see more charts in my dashboard than the API exposes. The dashboard uses additional internal endpoints (daily breakdowns, query clustering, domain lookups) that are not part of the public API. If you need one of them, contact us at contact@asknews.app — we would like to hear which numbers matter to you.
Can I use my organization's other domains?
Yes — pass several domain_names in one request. Any domain your organization does not own is dropped from the response, and a request with no owned domains returns 403.