APITube Documentation
Sign inGet started

Technical Questions and Answers ​

General Questions ​

How do I check the number of remaining requests? ​

Read the response headers to see how many requests you can still send:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 32
  • X-RateLimit-Limit: Total request limit
  • X-RateLimit-Remaining: Number of remaining requests
  • X-RateLimit-Reset: The number of seconds remaining until the rate limit resets

How many articles can I get in one request? ​

The per_page parameter controls how many articles are returned per page:

  • Default: 100 articles per page
  • Maximum: 250 articles per page, or 200 on Basic, 50 on Starter and 10 on Free — requesting more returns 400 ER0171 (Limit is out of range. Your plan allows up to N results per page.)

To get more results within your plan's limits, request the next page with page and per_page.

Free plan pagination limit: on the free plan you can only access the first 5 pages of results. Requesting page=6 or higher returns 400 ER0173. Upgrade to a paid plan to paginate beyond the first 5 pages.

How long are news articles stored in the system? ​

APITube stores news articles for 365 days from the publication date. After this period, articles are archived and not available through the general API. To access archived articles, contact our support service.

You can access the full 365 days, but a title search can cover at most 31 days per request. Use published_at.start and published_at.end to search one range at a time. A wider title-search range returns 400 ER0110; see Search window limit. Searches by category.id, entity.id or source.domain can cover all 365 days if they do not include a title search.

Authentication ​

What should I do if the API key doesn't work? ​

If your API key doesn't work:

  1. Copy the API key without extra spaces
  2. Check that the X-API-Key header is written correctly (case-sensitive)
  3. Make sure the key has not expired
  4. Check your account balance and limits
  5. Generate a new key in your APITube account

Can I use one API key for multiple applications? ​

Yes. Separate keys make it easier to manage access for each application.

How do I update or replace an API key? ​

To update or replace an API key:

  1. Log in to your account at APITube
  2. Go to "Settings" → "API keys"
  3. Click "Generate new key"
  4. Update the key in your application

Requests and Filtering ​

How do I use several filters at once? ​

Combine filters in one request. For example:

https://api.apitube.io/v1/news/everything?title=technology&language.code=en&category.id=medtop:20000002&published_at.start=NOW-7DAYS

This request will return articles about technology in English in the "Technology" category, published in the last 7 days. Because it searches the title, the published_at window may not exceed 31 days — see Search window limit.

What search operators does the query parameter support? ​

The query parameter supports the following operators:

  • Logical AND: technology AND innovation
  • Logical OR: technology OR innovation
  • Logical NOT: technology NOT blockchain
  • Grouping: (technology OR innovation) AND (AI OR "artificial intelligence")
  • Phrases: "artificial intelligence"
  • Word root search: technolog* (will find "technology", "technologies", "technological", etc.)

How do I find articles for a specific time period? ​

To search for articles for a specific period, use the published_at.start and published_at.end parameters:

https://api.apitube.io/v1/news/everything?published_at.start=2025-01-01&published_at.end=2025-01-31

This request will return articles published in January 2025.

Can I search for articles in several languages at once? ​

Yes, you can specify multiple languages by separating them with commas:

https://api.apitube.io/v1/news/everything?language.code=en,fr,de

This request will return articles in English, French, and German.

Integration and Development ​

What is the maximum API response size? ​

There is no fixed response-size limit. Responses grow with the number of articles and fields you request. Article text and entity details can make them large.

Use fl to request only the fields you need. For example, fl=id,title,href leaves out article text and other large fields. Reduce per_page if responses are still too large.

How do I handle API errors? ​

Always check the HTTP response code and status in the JSON response. When an error occurs, the API returns a not_ok status and error details:

json
{
    "status":"not_ok",
    "request_id":"fecf47d8-c90c-4c48-bdf0-bc34f6d41415",
    "errors":[
        {
            "code":401,
            "message":"API key is invalid or missing",
            "links": {
                "about":"https://docs.apitube.io/platform/news-api/http-response-codes"
            },
            "timestamp":"2025-05-11T17:02:46Z"
        }
    ],
    "user_input":null
}

Implement error handling in your code, for example:

javascript
try {
  const response = await axios.get('https://api.apitube.io/v1/news/everything', {
    params: { /* params */ },
    headers: { 'X-API-Key': API_KEY }
  });
  
  if (response.data.status === 'ok') {
    // Process successful response
  } else {
    // Handle error
    console.error(`API Error: ${response.data.message}`);
  }
} catch (error) {
  // Handle network or other exceptions
  console.error(`Request error: ${error.message}`);
}

How do I optimize API usage to save requests? ​

To use fewer requests:

  1. Cache results and reuse them while they are still useful.
  2. Use page and per_page to fetch only the articles you need.
  3. Narrow searches with specific filters.
  4. Combine searches that need the same results.
  5. Refresh data on a schedule and share the results across users.

Data Analysis ​

How do I interpret sentiment values in the response? ​

The sentiment field describes the tone of the article:

json
"sentiment": {
    "overall": {
        "score":0.07,
        "polarity":"positive"
    },
    "title": {
        "score":0.11,
        "polarity":"positive"
    },
    "body": {
        "score":0.03,
        "polarity":"positive"
    }
}

Each value represents the probability of the corresponding sentiment:

  • positive > 0.4: The article has a positive sentiment
  • negative > 0.4: The article has a negative sentiment
  • neutral > 0.4: The article has a neutral sentiment

If none of the values exceeds 0.4, the sentiment is considered mixed.

To get the most popular news, use the /v1/news/top-headlines endpoint and sort by relevance:

https://api.apitube.io/v1/news/top-headlines?category.id=medtop:13000000&sort.by=relevance&sort.order=desc

Yes, to track trending topics:

  1. Get articles for the desired period with the published_at.start and published_at.end parameters
  2. Group articles by categories or topics
  3. Count the number of articles in each category
  4. Sort categories by the number of articles
https://api.apitube.io/v1/news/everything?published_at.start=2025-01-01&published_at.end=2025-01-31&sort.by=relevance&sort.order=desc&per_page=100

Troubleshooting ​

Why am I getting a "Too Many Requests" error? ​

The "Too Many Requests" error (HTTP 429) occurs when you exceed the request limit for your subscription plan. To solve this problem:

  1. Check the number of remaining requests in the X-RateLimit-Remaining header
  2. Wait for the counter to reset (time in the X-RateLimit-Reset header)
  3. Cache and reuse results
  4. Request only the articles and fields you need
  5. Upgrade your subscription plan if necessary

Why am I getting an empty array of articles in the response? ​

If results is empty, check these possible causes:

  1. Filters are too strict — try simplifying the request
  2. There are no articles matching your criteria
  3. You are requesting data that is too old (more than 90 days)
  4. There is a problem with the request parameters — check the syntax

How do I distinguish duplicate articles in the results? ​

APITube automatically identifies duplicate articles and marks them with the is_duplicate field. You can filter duplicates using the is_duplicate=0 parameter:

https://api.apitube.io/v1/news/everything?is_duplicate=0

Why don't some articles contain the full text? ​

Full text may be unavailable because:

  1. The article is behind a paywall (the is_free field is false)
  2. Your subscription plan does not include access to the full text
  3. The publisher has restricted access to the full text
  4. An error occurred while extracting the text

In these cases, the API returns the available part of the text or only the title and description.

Security ​

How do I securely store the API key in my application? ​

Keep your API key in storage suited to your application:

  1. Server applications: Store the key in environment variables or a secure secrets vault
  2. Client web applications: Never store the key on the client, make requests through a proxy on your server
  3. Mobile applications: Use a secure storage, such as Keychain (iOS) or EncryptedSharedPreferences (Android)
  4. Desktop applications: Use the system credential store

Does the API have protection against SQL injections and other attacks? ​

Yes, APITube implements protection against all major types of web attacks:

  1. SQL injections
  2. XSS attacks
  3. CSRF attacks
  4. Command injection attacks
  5. DOS/DDOS attacks

All request parameters undergo strict validation before processing.

Advanced Usage ​

How do I use the API for brand reputation monitoring? ​

To follow news about your brand and its tone:

  1. Create a request specifying the brand name and sentiment analysis:
https://api.apitube.io/v1/news/everything?organization.name=Apple&sort.by=sentiment.overall.score
  1. Track changes in the sentiment of publications about the brand
  2. Set up alerts for negative publications
  3. Read the matching articles to understand why the brand is mentioned

Can I receive notifications about new articles on a specific topic? ​

To build your own notification checks:

  1. Schedule your code to check the API regularly, for example with a cron job
  2. Save the identifiers of already processed articles
  3. Compare new results with saved ones and identify new articles
  4. Send notifications through your preferred channel (email, push, webhook)

How do I get all articles by a specific author? ​

To get all articles by a specific author, use the author.name parameter:

https://api.apitube.io/v1/news/everything?author.name=John Doe&sort.by=published_at&sort.order=desc

How do I use the API for competitive analysis? ​

For competitive analysis:

  1. Create requests specifying the names of competing companies:
https://api.apitube.io/v1/news/everything?organization.name=Apple,Google,Microsoft&published_at.start=2025-01-01
  1. Compare the number of publications, sentiment, and topics
  2. Track product mentions and important events
  3. Analyze reactions to new products and competitors' initiatives

Integration with Other Services ​

Can I integrate APITube with Google Analytics? ​

Yes. Use Google Analytics to measure how people interact with the news you display:

  1. Create unique URL parameters for articles from APITube
  2. Add these parameters to article links
  3. Set up event tracking in Google Analytics
  4. Analyze user interaction with different news categories

How do I integrate APITube with BI (Business Intelligence) systems? ​

To integrate with BI systems:

  1. Fetch news from APITube on a schedule.
  2. Convert the response to the format your reporting system needs.
  3. Load the data into your reporting system or data warehouse.
  4. Build dashboards and reports from the news data.

Can I integrate APITube with CRM systems? ​

Yes. Use APITube to add relevant news to customer profiles in your CRM:

  1. Use your CRM's API to add news to company profiles
  2. Set up news searches about client companies through APITube
  3. Link news data to client profiles in the CRM
  4. Send managers an alert when new articles match the topics you choose

How do I create an RSS feed based on APITube data? ​

To create an RSS feed:

  1. Write a script that requests news from APITube
  2. Convert the articles to RSS (XML)
  3. Update the RSS feed on a schedule
  4. Host the feed on your web server or a service that supports RSS

Example of RSS generation:

php
<?php
$api_key = 'YOUR_API_KEY';
$url = 'https://api.apitube.io/v1/news/everything';

$params = [
    'query' => 'technology',
    'language' => 'en',
    'limit' => 20
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . '?' . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-Key: ' . $api_key
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

header('Content-Type: application/rss+xml; charset=utf-8');

echo '<?xml version="1.0" encoding="UTF-8"?>';
?>
<rss version="2.0">
  <channel>
    <title>Technology News</title>
    <link>https://yourdomain.com/tech-news</link>
    <description>Latest technology news</description>
    <language>en-us</language>
    <lastBuildDate><?= date(DATE_RSS) ?></lastBuildDate>
    <?php foreach ($data['articles'] as $article): ?>
    <item>
      <title><?= htmlspecialchars($article['title']) ?></title>
      <link><?= htmlspecialchars($article['url']) ?></link>
      <description><?= htmlspecialchars($article['description']) ?></description>
      <pubDate><?= date(DATE_RSS, strtotime($article['published_at'])) ?></pubDate>
      <guid><?= htmlspecialchars($article['article_id']) ?></guid>
    </item>
    <?php endforeach; ?>
  </channel>
</rss>

See the general FAQ for more answers, or contact support.