How to track news about a specific person#

To track a specific person, add person.name to a /v1/news/everything search — for example person.name=Tim Cook. APITube resolves the name against the people it already tracks and returns only articles that actually mention that person. Results come back newest-first by default, so re-running the same request on a schedule is already a working monitor — no sort parameter required.

curl "https://api.apitube.io/v1/news/everything?person.name=Tim Cook&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. The first article in the response is always the most recent mention, because the default sort is publication date in descending order.

How do I set up ongoing tracking for a person?#

Tracking a person is the person.name filter run on a schedule. The parameter matches people only (entity type person), so a company name passed to it returns “not found”. A few rules to know before you build the monitor:

• person.name accepts up to three names separated by commas, with OR logic — person.name=Tim Cook,Satya Nadella returns articles mentioning either person.
• Each name must be 1 to 120 characters and must match a tracked person. An unknown person.name returns HTTP 400 with error ER0216, so the request fails loudly instead of returning an empty list.
• Spaces should be URL-encoded (Tim%20Cook).

Because a name filter fails on the first name it cannot resolve, confirm the spelling before you schedule the job. For the full mechanics of how names map to entities, see how to find news mentioning a person or company.

How do I tell apart two people with the same name?#

Names are ambiguous — many people share one. To pin tracking to exactly one person, filter by their numeric entity.id instead of their name:

curl "https://api.apitube.io/v1/news/everything?entity.id=314&api_key=YOUR_API_KEY"

entity.id accepts up to three IDs (comma-separated, OR logic) and is type-agnostic. Each value must be an integer of 1 to 30 characters; a non-numeric value returns error ER0127 and an out-of-range length returns ER0128. Unlike a name, an entity.id is not checked against the directory, so it never blocks the request — a stable ID is the most reliable anchor for a long-running monitor.

To find the right ID, use entity autocomplete: GET /v1/suggest/entities with a prefix returns matching entities, each with its id, name and type. A missing prefix returns error ER0346.

curl "https://api.apitube.io/v1/suggest/entities?prefix=Tim&api_key=YOUR_API_KEY"

You can also read the id straight from the entities array of any article in a normal search response, then reuse it.

How do I only fetch mentions since my last check?#

Add a date window so each poll returns just the fresh coverage. published_at.start and published_at.end are inclusive and accept relative values, so published_at.start=NOW-1DAYS means “the last 24 hours”:

curl "https://api.apitube.io/v1/news/everything?person.name=Tim Cook&published_at.start=NOW-1DAYS&api_key=YOUR_API_KEY"

Relative expressions like NOW, NOW-7DAYS and NOW-1WEEK are resolved server-side, so your scheduled job never has to compute timestamps. Both bounds are 1 to 30 characters; an invalid value returns ER0104 (start) or ER0106 (end). To keep a competitor or noisy figure out of the results while you track your subject, use ignore.person.name — an unknown name there returns ER0217.

How do I follow sentiment toward the person?#

When you select a person, you can also restrict results by the tone expressed toward that person with entity.sentiment.polarity (positive, negative or neutral):

curl "https://api.apitube.io/v1/news/everything?person.name=Tim Cook&entity.sentiment.polarity=negative&api_key=YOUR_API_KEY"

A polarity other than the three allowed values returns ER0290. You can tighten it with the numeric range entity.sentiment.score.min and entity.sentiment.score.max, each between -1 and 1 (out-of-range values return ER0291 or ER0292). This is sentiment aimed at the person specifically, which is not the same as the article’s overall tone — see how to get sentiment toward a specific company or person for the entity-level breakdown.

How do I track a person in real time instead of polling?#

Instead of re-running a search every few minutes, open a Server-Sent Events stream that pushes each new matching article as it is published. The stream accepts the same entity filters:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?person.name=Tim Cook"

GET /v1/news/stream checks for new matches about every 30 seconds, sends up to 50 articles per cycle, sends a heartbeat every 30 seconds, and keeps the connection open for up to 6 hours before asking you to reconnect (error ER0362). Streaming draws on a separate streaming quota rather than your normal request credits. See how to stream news in real time with SSE for resume handling and message format. For the complete list of accepted parameters, see the official parameters reference.

Common Questions#

• Should I track by person.name or entity.id?
• How many people can I track in one request?
• Why does my person filter return no articles?
• How do I confirm the article really mentions the right person?

Should I track by person.name or entity.id?#

Both target the same people. A person.name is easier to read, but it must exactly match a tracked person or the request fails with ER0216. A numeric entity.id is more robust for a long-running monitor: it is a fixed identifier, is not validated against the directory, and never blocks the request — an unknown ID simply returns no articles. For anyone whose name is shared by several people, entity.id is the safer anchor.

How many people can I track in one request?#

Up to three per parameter. person.name, entity.id and their ignore. variants each accept a comma-separated list, and only the first three values are applied. Multiple values inside one parameter use OR logic, so an article matches if it mentions any of them. To watch more than three people, run several requests or open several streams.

Why does my person filter return no articles?#

Either the name resolved but there is no recent coverage, or your other filters are too tight. A name filter fails loudly — an unknown person.name returns ER0216 rather than an empty list — so a clean empty response means the person was found but matched nothing. Widen the date window (drop published_at.start), remove entity.sentiment.polarity, or switch to the person’s numeric entity.id to rule out a name mismatch.

How do I confirm the article really mentions the right person?#

Every article carries an entities array. Each entry has the person’s id, name, type, a frequency count of how many times they are mentioned, and the sentiment toward them. Read the id from there to lock future requests to the exact person with entity.id, and check frequency to tell a passing mention from an article that is actually about them.