News API v3 implements rate limits and quotas to ensure fair usage and maintain service quality for all users. This guide explains how these limits work and how to monitor your usage.

​
Understanding your limits

Your subscription plan defines the following usage limits:
  • Concurrent calls: The number of simultaneous API requests you can make.
  • Plan calls: The total number of API calls allowed per month.
  • Historical days: The number of days in the past you can retrieve articles.

​
Checking your subscription

You can view your current subscription details and remaining quota by making a request to the /subscription endpoint.

​
Example request

curl -X GET "https://v3-api.newscatcherapi.com/api/subscription" \
 -H "x-api-token: YOUR_API_KEY_HERE"
Replace YOUR_API_KEY_HERE with your actual API key. Use cURL, Postman, or any other tool to make HTTP requests.

​
Example response

The response will look similar to this: 
{
  "active": true,
  "concurrent_calls": 10,
  "plan": "v3_nlp_iptc_tags",
  "plan_calls": 250000,
  "remaining_calls": 99986,
  "historical_days": 400
}

​
Response format

​
active
boolean
Indicates if your subscription is currently active.
​
concurrent_calls
integer
The maximum number of simultaneous API requests you can make.
​
plan
string
Your subscription plan name.
​
plan_calls
integer
The total number of API calls allowed in your subscription period.
​
remaining_calls
integer
The number of API calls you have left in your current period.
​
historical_days
integer
The number of days in the past you can retrieve articles for.

​
Rate limit behavior

If you exceed your rate limit for concurrent calls, you receive a 429 (Too many requests) error. When this happens, wait a short time before retrying your request. In production, consider implementing robust error handling and retry mechanisms, such as exponential backoff or adaptive throttling, to dynamically adjust the frequency of requests based on the server response. This approach helps prevent hitting rate limits repeatedly and ensures smoother interactions with the API, improving both reliability and user experience.

​
Quota reset

Your quota of total calls (plan_calls) typically resets monthly at the beginning of each billing cycle. The exact reset time depends on your specific subscription terms. Any remaining calls from the previous month do not carry over to the next month.

​
Best practices

To make the most of your subscription and avoid hitting limits:
  1. Monitor your usage regularly using the /subscription endpoint.
  2. Implement efficient error handling in your code, especially for 429 errors.
  3. Optimize your queries to retrieve only the data you need. Use filters and parameters effectively to reduce unnecessary API calls.
  4. For time-sensitive applications, consider implementing a polling strategy with appropriate intervals rather than constant real-time requests.
  5. If you’re building a user-facing application, consider implementing pagination or “load more” functionality to fetch additional results only when needed.
  6. If you consistently reach your limits, consider upgrading your plan to better suit your needs.
Remember, news data is highly dynamic, with millions of new articles added daily. Avoid caching article data for extended periods, as this could lead to outdated information. Instead, focus on efficient real-time data retrieval strategies.
If you have any questions about your rate limits or need to increase your quota, contact our support team.