How to return only specific fields with fl#

The APITube News API fl parameter returns only the fields you list instead of the full article object. Pass a comma-separated list — fl=id,title,published_at — and every item in the results array is trimmed to exactly those keys. Use dot notation such as source.domain to reach nested fields. This shrinks the response and speeds up parsing when you only need a few values per article.

curl "https://api.apitube.io/v1/news/everything?title=tesla&fl=id,title,published_at&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, and fl works the same whether you put it on a GET query string or in a POST JSON body.

How does the fl parameter work?#

fl takes a comma-separated list of field names. The API formats each full article as usual, then keeps only the listed keys before sending the response. With fl=id,title,published_at, each object in results looks like this and nothing else:

{
  "id": 1234567,
  "title": "Tesla reports record quarterly deliveries",
  "published_at": "2026-06-26T08:15:00.000Z"
}

The response wrapper does not change. The top-level fields — status, page, limit, has_next_pages, next_page and the export links — are always present. fl only shapes the article objects inside results, so your pagination loop keeps working exactly as before.

How to select nested fields with dot notation#

Many article fields are nested objects — source, sentiment, author, readability. To pick a value inside one of them, write the path with a dot. The API rebuilds just that branch of the object and drops everything else.

curl "https://api.apitube.io/v1/news/everything?fl=id,source.domain,sentiment.overall.polarity&api_key=YOUR_API_KEY"

Each result then contains only the requested branches:

{
  "id": 1234567,
  "source": { "domain": "reuters.com" },
  "sentiment": { "overall": { "polarity": "positive" } }
}

You can mix flat and nested paths freely, for example fl=title,author.name,source.bias. To narrow results to one publisher first, combine fl with a source filter.

Which endpoints support fl?#

fl works on the article-returning endpoints, including /v1/news/everything, /v1/news/top-headlines, /v1/news/local, /v1/news/article and /v1/news/story/:id. The behaviour is identical on each — list the fields you want and every returned article is trimmed to them.

curl "https://api.apitube.io/v1/news/top-headlines?fl=id,title,href,image&api_key=YOUR_API_KEY"

Common Questions#

What happens if I request a field that does not exist?#

Unknown field names are silently skipped — there is no error. If you ask for fl=id,foobar, each result returns just { "id": ... } because foobar has no value to include. If none of the names you list exist, each item in results comes back as an empty object {}. Check field names against the official News API parameters reference so you do not accidentally drop the data you wanted.

Does fl reduce how many requests I am charged?#

No. Each call still counts as one request against your quota or balance, whether you return one field or the whole article. fl trims the payload to make responses smaller and faster to parse; it does not change billing. Use it to cut bandwidth and client-side work, not to save credits.

Can I use fl with CSV, XLSX and other exports?#

Yes. The field selection is applied before the export file is generated, so an export=csv (or xlsx, tsv, xml) response contains only the columns you selected with fl. This is handy for building a lean spreadsheet with, say, fl=published_at,title,source.domain.

Which errors can fl return?#

Both fl errors are 400 responses. ER0300 (“fl must be a string.”) is returned when the value is not a string, and ER0301 (“fl cannot be empty.”) is returned when you send fl with no usable field names — for example fl= or fl=,,. Send a plain comma-separated list of names and you will not hit either one.