Frequently Asked
Questions

Everything about the API, the plans, and your account, in one place. If you don't find your answer here, contact us.

Getting started

GNews API is a real-time news API for developers. Search articles or get top headlines by category from 80,000+ sources in 41 languages and 71 countries, returned as JSON. Developers build news feeds, media monitoring tools, analytics, AI agents, RAG pipelines, and research projects on it. You can start on the Free plan.

Sign up, verify your email address, and copy the API key from your dashboard. Your account starts on the Free plan. If you sign up with Google, your email address will be verified automatically.

No. The Free plan never asks for payment details. You add a payment method only when you start a paid plan or its free trial.

Send a GET request with your API key, such as https://gnews.io/api/v4/search?q=AI&lang=en&apikey=YOUR_API_KEY, and read the JSON response. To build requests without writing code, use the API Playground in your dashboard. Every parameter is described in the documentation.

Two. The Search endpoint (/api/v4/search) finds articles by keyword, with search operators, language and country filters, a date range, sorting, and pagination. The Top Headlines endpoint (/api/v4/top-headlines) returns the current top headlines of a category: general, world, nation, business, technology, entertainment, sports, science, or health.

Plans and free trial

The daily quota, the articles per request, freshness, and historical data. Paid plans go from 1,000 to 25,000 requests per day and up to 100 articles per request, with real-time articles, historical data since 2020, full article content, CORS for all origins, and email support. The Free plan has 100 requests per day, up to 10 articles per request, a 12-hour delay, and the last 30 days of historical data. Compare them on the Pricing page.

Start the 10-day free trial of any paid plan from the Pricing page. You add a payment method. If you cancel before the trial ends, you won't be charged. The trial is available once per account. If the trial doesn't become a paid subscription, you can't use any data retrieved during it for commercial purposes.

No. A commercial project requires a paid plan for as long as it uses GNews API. The Free plan is for personal, academic, evaluation, and other non-commercial projects. Developing and testing an integration that isn't published or in production yet isn't commercial use. Commercial use means any product, service, or project that is sold, earns revenue, or is used in the course of a business. Accounts that break this rule can be suspended or closed. Full conditions are in the Terms of Service.

Yes, with a paid plan, for as long as the product uses GNews API. Article text and images belong to their owners: respect their copyright and don't present the content as your own. Full conditions are in the Terms of Service.

No. Attribution is welcome but not required, unless your plan says otherwise.

20% compared with paying monthly. For example, the Essential plan costs €479.99/year instead of €599.88 for 12 monthly payments. Switch the toggle to Yearly on the Pricing page to see every plan.

Custom plans start from the Essential plan: raise the daily quota and the articles per request, choose your support level, and ask for features we don't offer as standard. Contact us with the volume and the features you need.

Billing and subscription

Stripe processes all payments. You can pay by card, including Cartes Bancaires, or with Alipay, Amazon Pay, Apple Pay, Google Pay, Link, PayPal, or SEPA Direct Debit. The checkout page shows the methods available for your country and device. Your payment details go to Stripe and never reach our servers.

  1. Go to the Change Plan page from Plan & Billing.
  2. Pick the plan and the billing frequency.
  3. Check how the change is billed, then confirm.

The new limits will apply as soon as you confirm. A yearly plan can't go back to monthly billing. On the Free plan, pick a plan on the Compare Plans page and complete the checkout.


When you upgrade, you'll be charged the prorated price difference. A downgrade will turn it into a credit on your balance, applied automatically to your next invoices. In both cases, your renewal date will stay the same. Switching from monthly to yearly billing will charge the yearly price minus proration, and your renewal date will move to the day you switch: the plan will renew yearly from that date. During a trial, you won't be charged: the new plan's price will apply when the trial ends. Every adjustment will appear in your invoices on Plan & Billing.

Yes, at no cost:
  1. Go to Plan & Billing.
  2. Click Cancel subscription.
  3. Choose a reason, then confirm.

You'll keep your plan until the end of your billing period. After that, your account will move to the Free plan. Until your billing period ends, Resume subscription on the same page undoes the cancellation, and so does changing your plan. If you cancel before the trial ends, you won't be charged.


You can ask for a refund within 7 days of your initial subscription or of a renewal, if you haven't made any request in that period. When you subscribe without a free trial, the first month's payment can't be refunded. Write to contact@gnews.io with a short explanation. We aim to review requests within 3 to 5 business days, and an approved refund usually reaches your account 5 to 10 business days later. Requests we consider fraudulent or abusive can be refused. Full details are in the Terms of Service.

It keeps working, and your account moves to the Free plan: 100 requests per day, a 12-hour delay, and the last 30 days of historical data. The right to use the API in a commercial project ends with the subscription, including on the Free plan. Data you retrieved while subscribed can stay in your project, except data from a trial that didn't become a paid subscription. Resubscribe and the paid limits will apply again.

Stripe can retry the payment up to 4 times over 2 weeks, and emails you each time. Pay the overdue invoice on Plan & Billing during that time to keep your subscription. If you don't pay it, your subscription will end and your account will move to the Free plan.

News data and coverage

80,000+ sources, in 41 languages and 71 countries. The Search endpoint supports fewer languages and countries than the Top Headlines endpoint. See the lists on Search Endpoint and Top Headlines Endpoint in the documentation.

Use the form on the Suggest a Missing Source page. List each source's URL, one per line. Add its name and country if you know them.

To 2020 on paid plans, with the from and to parameters. The Free plan covers the last 30 days: older articles are left out, and the response says how many. See Article Availability in the documentation.

In real time on paid plans, as soon as they're indexed. On the Free plan, articles arrive with a 12-hour delay: articles published in the last 12 hours aren't returned.

Yes, on paid plans: content holds the full text of the article. On the Free plan, it's cut to 250 characters. On any plan, add truncate=content to get the shorter version.

Not yet. Source filtering is on our roadmap. Every article includes a source object (name, home page URL, and, on the Search endpoint, country), so you can filter or group articles on your side.

By default, articles without a description, content, or image are left out. Some sources don't provide a summary or a cover image. To include those articles, list the fields allowed to be null with nullable, for example nullable=description,image.

totalArticles counts every article that matched your request. The response holds one page of them. Raise max up to the limit of your plan (up to 100 on paid plans, 10 on the Free plan) and step through the pages with page. Pagination stops at 1,000 articles, so narrow the query or the date range to go further.

The selection is based on Google News rankings for the category, language, and country you ask for. The API then returns the most recent articles first.

Using the API

Send your API key in the apikey query parameter or the X-Api-Key header. On a server, prefer the header, which keeps the API key out of URLs and server logs. A missing or malformed API key returns a 400 error. A well-formed API key that doesn't match any account returns a 401 error. See Authentication in the documentation.

q takes at most 200 characters, with exact phrases, parentheses, and the AND, OR, and NOT operators. A space works as AND. OR has higher precedence than AND, so add parentheses when you mix them. URL-encode the query. On the Search endpoint, in sets the fields searched. See Query Syntax in the documentation.

  • 400: The API key is missing or malformed, or the q parameter is missing, too long, or has a syntax error.
  • 401: The API key is well-formed but doesn't match any account.
  • 403: The account's email address isn't verified, or the daily quota is used up.
  • 404: The endpoint doesn't exist, or the request doesn't use GET.
  • 429: Too many requests per second: 10 on paid plans, 1 on the Free plan.
  • 500: An unexpected problem on our side.
  • 503: A temporary problem on our side.

Every message is listed in Error Handling, in the documentation.


The API returns a 403 error until the quota resets at 00:00 UTC. Unused requests don't carry over to the next day. Follow your usage on the dashboard, and upgrade when you need a higher daily quota.

Yes: 10 requests per second on paid plans, 1 on the Free plan. Above that, the API returns a 429 error. Space out your requests, and retry after a short wait with exponential backoff.

On paid plans, yes: CORS allows every origin. On the Free plan, CORS only allows localhost, so browsers block requests from a deployed website. An API key in front-end code is visible to anyone, so on a public website, call the API from your backend.

Libraries and integrations

No. It's a REST API over HTTPS, so any HTTP client works. The official SDKs handle authentication, errors, retries, and response parsing for you.

SDKs for Python, JavaScript/TypeScript (Node.js and the browser), and PHP, plus LangChain tools for AI agents. Install commands are on the Libraries & SDKs page.

Yes. pip install langchain-gnews gives LangChain and LangGraph agents two tools: news search with historical data since 2020, and top headlines by category and country. It uses your API key. See the LangChain page in the documentation.

Yes. The hosted MCP server lets AI assistants such as Claude Code, Cursor, VS Code, and Gemini CLI search news and get top headlines with your API key, without installing anything.

Yes. Send the repository or package URL with the form on the Libraries & SDKs page. We list community projects that are documented and maintained.

Account and support

Verification codes expire after 15 minutes. Request a new code on the Verify Your Email Address page, which opens when you sign in, and check your spam folder. If it still fails, write to contact@gnews.io from the email address you signed up with, and we'll verify it for you.

Open the Forgot Your Password? page and we'll email you a link to choose a new password. When you're signed in, you can change it on the Account page. Accounts created with Google have no password: use the Continue with Google button instead.

On the Account page, click Generate a new API key, then confirm. Your current API key will stop working as soon as you generate the new one. Projects that use it will get 401 errors until you switch them to the new API key.

  1. If you have a subscription, cancel it on Plan & Billing and wait until it ends.
  2. On the Account page, click Delete account.
  3. Type DELETE, then confirm.

Deleting your account is permanent. Once it's deleted, any request you send to the API will return a 401 error. Your account data will be erased, apart from the records the Privacy Policy lists, such as invoices.


Write to contact@gnews.io, use the contact form, or start a chat. Paid plans include email support: a reply within 1 business day, and help with your integration. The Enterprise plan includes premium email support: priority replies, and advanced help with your integration, such as query design and data pipelines.

Within 1 business day on paid plans. Include your account's email address, your plan, and, for a technical issue, the request URL without your API key, and the response you got: that usually solves it in one reply.

Students and education

Students, researchers, and teachers working on an academic project, a thesis, or coursework at a recognized institution. We review each request by hand.

The Essential plan, for free: 1,000 requests per day, up to 25 articles per request, real-time articles, historical data since 2020, full article content, CORS for all origins, all 80,000+ sources, and email support.

Access runs until the date in your approval email, set from your project. After that, your account moves to the Free plan.

  1. Sign up for free.
  2. Fill in the application form with the email address of your GNews API account. An institutional email address makes the review faster.
  3. Describe your project or research, your institution, and your role.

We review each request by hand and email you to let you know whether it's approved or not.


No. Academic access is free, so you can't use the data for commercial purposes. If your project starts earning revenue or ships as a commercial product, you must move to a paid plan: contact us to end your academic access, then subscribe. Accounts that break this rule can be suspended or closed.

You keep your account on the Free plan, and you can reply to our email with more detail about your project or institution so we can review it again. Paid plans, each with a 10-day free trial, are on the Pricing page.

Switching from another news API

Volume for the price. Paid plans start at €49.99/month for 1,000 requests per day, with real-time articles, historical data since 2020, and full article content included, not sold as add-ons. Every plan covers all 80,000+ sources, and paid plans include email support.

Usually an afternoon. There are two REST endpoints, authentication is one API key, and the response is flat: totalArticles and an articles array where each article holds its text (title, description, content), its URL and image, its publication date and language, and its source. Most migrations swap the base URL, rename a few query parameters, and remap those fields. The documentation and the official SDKs cover the rest.

Yes. Start on the Free plan to check the data and your integration, then start the 10-day free trial of a paid plan to test real-time articles, full article content, and production volumes. If you cancel before the trial ends, you won't be charged.

Google News API

No. Google shut down its Google News Search API in 2011, and nothing official has replaced it. Developers now use the Google News RSS feeds, SERP scraping APIs that return Google's result pages as JSON, or an independent news API such as GNews API, which returns top headlines based on Google News rankings and keyword search across 80,000+ sources.

No. GNews API is an independent service, not affiliated with, endorsed by, or sponsored by Google. Top headlines are based on Google News rankings. The index, the infrastructure, and the support are our own.

Not exactly. The Top Headlines endpoint picks the top headlines of a category, language, and country based on Google News rankings, then returns them with their content from our own index of 80,000+ sources. The Search endpoint queries that index directly, with operators and date filters Google News doesn't offer. To mirror what a Google News page shows, use a SERP scraping API. For structured articles and search, use GNews API.

Google has no news API to price. The Google News RSS feeds are free but only carry a title, a link, a date, and a source name, and SERP scraping APIs charge per result. GNews API has a Free plan: 100 requests per day, up to 10 articles per request, a 12-hour delay, and the last 30 days of historical data, for personal, academic, evaluation, and other non-commercial projects. Paid plans start at €49.99/month for 1,000 requests per day, with real-time articles, historical data since 2020, and full article content. Every paid plan starts with a 10-day free trial.

Scrapers break: layouts change, requests get blocked, and articles need deduplicating and cleaning. GNews API gives you a documented contract instead: one API key, two endpoints, consistent JSON, and article content already extracted.

Didn't find your answer?

On the Contact page, you can send us a message or start a chat.

Contact us

Ready to build
with GNews API?

Get your API key and make your first request in minutes.