How to monitor competitor brands#

To monitor competitors, put their names in organization.name or brand.name on /v1/news/everything and read the results newest-first. One request can watch up to three rivals at once, entity.sentiment.polarity shows how each one is being talked about, and ignore.brand.name lets you follow the rest of your category while cutting out your own coverage. This tracks three sportswear rivals over the last week:

curl "https://api.apitube.io/v1/news/everything?brand.name=Nike,Adidas,Puma&published_at.start=NOW-7DAYS&language.code=en&api_key=YOUR_API_KEY"

Send the key as an X-API-Key: YOUR_API_KEY header instead of the api_key query parameter if you prefer. Because the default sort is published_at descending, the freshest competitor story is already at the top — no sort parameter needed.

How do I track a single competitor’s news?#

Point one name filter at the rival: organization.name for a company, brand.name for a consumer brand. APITube resolves the name against the entities it tracks and returns only articles that actually mention that entity, so you avoid the false hits a plain keyword search produces. Add language.code to stay in one language and published_at.start to scope a window.

curl "https://api.apitube.io/v1/news/everything?organization.name=Adidas&published_at.start=NOW-24HOURS&api_key=YOUR_API_KEY"

If the name is not tracked or is misspelled, the request returns a “not found” error rather than empty results. When that happens, switch to the numeric entity.id, which never changes for a given company and is the most reliable way to pin one exact competitor. The find news mentioning a person or company guide shows how to look up that ID.

How do I watch several competitors in one request?#

Both organization.name and brand.name accept up to three comma-separated values, and those values are matched with OR logic — so brand.name=Nike,Adidas,Puma returns any article that mentions at least one of the three. The entity.id filter works the same way, accepting up to three IDs at once, which is the sturdier option once you know each rival’s identifier:

curl "https://api.apitube.io/v1/news/everything?entity.id=314,42,88&published_at.start=NOW-7DAYS&api_key=YOUR_API_KEY"

Three is the hard limit per request: extra comma-separated values beyond the third are dropped. To follow more than three competitors, run one request per group of three, or split them into separate saved searches. Keep each rival’s entity.id on hand so a rename or a spelling variant never breaks the watch.

How do I follow my category but exclude my own brand?#

Competitive monitoring often means “everything in my space except us.” Use the ignore. variants — ignore.brand.name or ignore.organization.name — to subtract your own coverage from a broader search. Pair a category-defining title search with an exclusion of your brand so the feed is your rivals and the wider conversation, minus your own press:

curl "https://api.apitube.io/v1/news/everything?title=running%20shoes&ignore.brand.name=Nike&language.code=en&api_key=YOUR_API_KEY"

Words in a title search are combined with AND, so title=running shoes keeps articles whose headline contains both words. Layering ignore.brand.name=Nike on top removes anything that mentions your own brand, leaving the competitive landscape around you. Like the positive filters, the ignore. name filters accept up to three comma-separated values, so you can exclude a house of brands in one shot.

How is each competitor being talked about?#

Add entity.sentiment.polarity next to a name filter to keep only articles whose tone toward that specific rival is positive, negative or neutral. This is measured per entity, not for the article as a whole, so a broad market piece that quotes several brands is judged on how it treats the competitor you named — not its average mood:

curl "https://api.apitube.io/v1/news/everything?brand.name=Adidas&entity.sentiment.polarity=negative&published_at.start=NOW-7DAYS&api_key=YOUR_API_KEY"

Entity-level tone is different from sentiment.overall.polarity, which describes the whole article. For competitor work the entity-level filter is usually what you want, because it catches a story that is rough on a rival even when the overall piece reads as balanced. See how to get sentiment toward a specific company or person for the full breakdown of that distinction.

How do I surface a competitor’s biggest stories first?#

By default results are newest-first, which is right for a live watch but buries the story that actually mattered. Switch sort.by to engagement to rank a rival’s coverage by importance instead of timestamp — the engagement score blends signals such as breaking-news flags, image and video richness, positive overall sentiment, freshness, and the source’s rank, so the loudest stories rise to the top:

curl "https://api.apitube.io/v1/news/everything?organization.name=Tesla&sort.by=engagement&sort.order=desc&per_page=20&api_key=YOUR_API_KEY"

sort.order accepts asc or desc and defaults to desc. Other useful modes are relevance (best headline match for your title terms), quality, and trust. Pull more rows per call with per_page, which tops out at 250, and page through the rest with page.

How do I keep a live watch on competitors?#

Re-running the same search on a timer wastes requests and adds lag. The /v1/news/stream endpoint accepts the exact same competitor filters and pushes each new matching article over Server-Sent Events (SSE) shortly after it is indexed, sending only articles newer than the ones you have already seen:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?brand.name=Nike,Adidas,Puma&language.code=en"

That gives you a clean, continuous feed of fresh competitor mentions rather than a repeat of your backlog. For a fully hands-off alert that calls your own server when a rival is in the news, set up a webhook on a saved search — webhooks are created in the dashboard, not through an API call.

Common Questions#

• How many competitors can I track in one call?
• A competitor’s name returns an error. What now?
• How is this different from measuring share of voice?

How many competitors can I track in one call?#

Three. The name filters organization.name and brand.name, and the numeric entity.id, each accept up to three comma-separated values in a single request, matched with OR logic. The same three-value limit applies to the ignore. exclusions. To watch a larger set, split the rivals across several requests or several saved searches and merge the feeds on your side.

A competitor’s name returns an error. What now?#

Name filters resolve against the entities APITube tracks, so an untracked or misspelled competitor name returns a “not found” error instead of empty results. Switch to that company’s numeric entity.id, which is stable and never changes, or look up the correct identifier first. The monitor a company or brand guide walks through finding and using an entity.id.

How is this different from measuring share of voice?#

Monitoring is about reading the stream of competitor coverage as it happens; share of voice is about counting it. When you want totals — how many articles mention each rival, or each brand’s slice of category coverage — use the /v1/news/count endpoint and facets instead of paging through articles. See how to measure PR and media coverage for the counting workflow.