How Do I Reduce API Response Size and Improve Performance? NewsDataHub Fields Parameter Guide

intermediate 10 min read October 14, 2025

news apiperformancepayload optimizationbandwidthfields parameterapi efficiencydeveloper guide

🧭

TL;DR: Use the fields parameter to request only the data you need (title, description, url, etc.), reducing bandwidth and improving performance. Specify comma-separated field names in your request to optimize API responses for your use case.

Use the fields parameter with GET /v1/news, GET /v1/top-news, and GET /v1/news/{article_id}/related to request only the fields you need. This guide explains syntax, practical combinations, performance benefits, and ready‑to‑run curl examples to reduce payload size and improve response times.

What is NewsDataHub? It’s a developer‑friendly news API that aggregates and normalizes global news from mainstream outlets, digital‑native publishers, press releases, and specialty sources. We ingest over 150,000 articles daily and standardize metadata like language, topics, source type, reliability, and political leaning so you can build precise, repeatable news API filtering without curating long source lists.

Why payload optimization matters: reducing the size of API responses improves load times, reduces bandwidth costs, and makes your application faster for end users. By requesting only the fields you need, you avoid transferring unnecessary data and can process responses more efficiently. This is especially critical for mobile applications, high‑traffic services, and scenarios where you’re making many API requests.

Note: Examples below use GET /v1/top-news because it returns cleaner mainstream results over the last 24–72 hours. The fields parameter works identically with GET /v1/news and GET /v1/news/{article_id}/related.

Related guides for deeper context:

• Top News endpoint
• Advanced Search & Filtering

Why Control Response Payload Size

• Faster load times: Smaller payloads mean faster network transfer and quicker parsing, improving user experience.
• Reduced bandwidth costs: Minimize data transfer for both your application and end users, especially important for mobile users with limited data plans.
• Improved performance: Less data to parse means faster JSON deserialization and reduced memory footprint.
• Simpler processing: When you need only specific fields, your application code becomes cleaner and more focused.
• Efficient caching: Smaller responses are easier to cache and take up less cache storage.
• Better mobile experience: Reduced payload sizes directly translate to better performance on mobile devices with limited resources.
• Lower infrastructure costs: Less bandwidth usage means lower hosting and CDN costs, especially at scale.

What Is the fields Parameter?

It’s a comma‑separated list of field names that controls which article properties are included in the API response. When specified, only the requested fields are returned along with the id field, which is always included. This parameter works identically across all news endpoints.

How the Fields Parameter Works

When you don’t specify the fields parameter on GET /v1/news and GET /v1/top-news, NewsDataHub returns all available fields for each article. This includes:

• id (always included)
• title
• source_title
• source_link
• article_link
• keywords (Basic/Pro tiers only)
• topics (Basic/Pro tiers only)
• description
• pub_date
• creator
• content
• media_url
• media_type
• language
• sentiment (Basic/Pro tiers only)
• source (nested object with source metadata)

By using the fields parameter, you can request only what you need. For example, if you’re building a headline feed, you might only need title, pub_date, and article_link.

Endpoints That Support It

• GET /v1/top-news — Curated mainstream coverage from the last 24–72 hours.
• GET /v1/news — Full article stream with historical access and rich filters.
• GET /v1/news/{article_id}/related — Find articles similar to a given article (note: this endpoint has a different response structure with related_to, count, and data fields).

Authentication

Include your API key in X-API-Key. A convenient pattern is an environment variable:

export NEWSDATAHUB_API_KEY='YOUR_API_KEY_HERE'

See our docs on how to authenticate: Authentication

Usage Patterns

Return only essential fields (title and publication date):

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'fields=title,pub_date' \
  --data-urlencode 'per_page=5'

Minimal feed with headlines, source, and links:

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'fields=title,source_title,article_link,pub_date' \
  --data-urlencode 'per_page=5'

Include description for article previews:

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'fields=title,description,article_link,pub_date,source_title' \
  --data-urlencode 'per_page=5'

Request media information for visual feeds:

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'fields=title,media_url,media_type,article_link' \
  --data-urlencode 'per_page=5'

Combine with Topics, Search, and Filters

Optimized technology news feed with minimal fields:

# Technology headlines with source and date
curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'topic=technology' \
  --data-urlencode 'country=US' \
  --data-urlencode 'fields=title,pub_date,source_title,article_link' \
  --data-urlencode 'per_page=5'

Search with only title and links (fastest response):

# Boolean search returning minimal data
curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'q="artificial intelligence" AND (ChatGPT OR OpenAI)' \
  --data-urlencode 'fields=title,article_link' \
  --data-urlencode 'per_page=5'

Filter by political leaning with description for context:

# Center-leaning sources with headlines and descriptions
curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=48' \
  --data-urlencode 'topic=politics' \
  --data-urlencode 'political_leaning=center' \
  --data-urlencode 'fields=title,description,article_link,pub_date,source_title' \
  --data-urlencode 'per_page=5'

Using with the historical news endpoint:

# Historical search with date range and selective fields
curl -G https://api.newsdatahub.com/v1/news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'q=climate change' \
  --data-urlencode 'start_date=2025-09-01' \
  --data-urlencode 'end_date=2025-09-30' \
  --data-urlencode 'fields=title,pub_date,source_title,article_link' \
  --data-urlencode 'per_page=5'

Response Shape: Requested Fields Only

When you use the fields parameter, the response includes only the requested fields plus id (which is always included). Here’s an example comparing a filtered vs. full response.

Request with fields parameter:

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=72' \
  --data-urlencode 'q=openai' \
  --data-urlencode 'fields=title,pub_date,article_link' \
  --data-urlencode 'per_page=1'

Response with selective fields — Notice how only the requested fields (plus id) are returned, resulting in a much smaller payload:

{
  "next_cursor": "MzMuNzY0NTcsMTc2MDM3NzM0MTAwMCwyMTEwNjE1Njg=",
  "total_results": 75,
  "per_page": 1,
  "data": [
    {
      "id": "2dc425b4-5286-4231-877a-e77b861e3395",
      "title": "Oracle CEO Magouyrk: 'Of course' OpenAI can pay $60 billion per year",
      "pub_date": "2025-10-13T17:42:21",
      "article_link": "https://www.cnbc.com/2025/10/13/oracle-ceo-magouyrk-of-course-openai-can-pay-60-billion-per-year.html"
    }
  ]
}

Same request without fields parameter:

curl -G https://api.newsdatahub.com/v1/top-news \
  -H "X-API-Key: $NEWSDATAHUB_API_KEY" \
  -H "User-Agent: newsdatahub-fields-parameter/1.0-curl" \
  --data-urlencode 'hours=72' \
  --data-urlencode 'q=openai' \
  --data-urlencode 'per_page=1'

Response with all fields — Without the fields parameter, the API returns all available fields, significantly increasing payload size:

{
  "next_cursor": "MzMuNjU2NTU1LDE3NjAzNzczNDEwMDAsMjExMDYxNTY4",
  "total_results": 75,
  "per_page": 1,
  "data": [
    {
      "id": "2dc425b4-5286-4231-877a-e77b861e3395",
      "title": "Oracle CEO Magouyrk: 'Of course' OpenAI can pay $60 billion per year",
      "source_title": "CNBC",
      "source_link": "https://cnbc.com",
      "article_link": "https://www.cnbc.com/2025/10/13/oracle-ceo-magouyrk-of-course-openai-can-pay-60-billion-per-year.html",
      "keywords": [
        "oracle",
        "david faber",
        "infrastructure",
        "intelligence",
        "integrating",
        "openai artificial intelligence",
        "artificial intelligence models",
        "integrating openai artificial"
      ],
      "topics": [
        "technology",
        "business",
        "finance",
        "cloud computing",
        "artificial intelligence"
      ],
      "description": "In July, OpenAI signed a five-year cloud deal with Oracle, which is confident that the startup will be able to pay its bills.",
      "pub_date": "2025-10-13T17:42:21",
      "creator": "CNBC",
      "content": "Oracle CEO Clay Magouyrk, one of the two people tapped last month to lead the software company, is confident that OpenAI will be able to cover the costs of the massive amount of cloud infrastructure services it consumes. In an interview with CNBC's David Faber at Oracle's AI World conference on Monday, Magouyrk said \"of course\" OpenAI can pay $60 billion for a year's worth of cloud resources. In July, OpenAI agreed to a five-year deal with Oracle that's worth over $300 billion. \"Just look at the rate at which they've grown to, you know, almost a billion users. That's just unheard of,\" said Magouyrk, who sat alongside fellow Oracle CEO Mike Sicilia for the interview in Las Vegas. OpenAI said last week that its flagship ChatGPT chatbot, which was publicly launched less than three years ago, now has 800 million weekly active users. In 2024, OpenAI recorded a $5 billion net loss. Sicilia said Oracle has started integrating OpenAI artificial intelligence models into a patient portal for viewing electronic health records. Oracle acquired EHR vendor Cerner for about $28 billion in 2022. \"I've seen the results, and I really do think that they're going to have a dramatic impact on industries, on enterprises of all types,\" Sicilia said of OpenAI. OpenAI rents out Nvidia graphics chips to run models through Oracle, as well as CoreWeave Google and Microsoft At the same time, the company is designing a custom AI processor that Broadcom will build. Earlier on Monday, Broadcom and OpenAI said they will jointly deploy 10 gigawatts worth of the new OpenAI chips. Building out that much infrastructure requires a hefty amount of new energy. \"I think it's a factor of time, not a factor of if we'll have enough power,\" Sicilia said. Oracle shares rose almost 6% on Monday. The stock has gained 86% this year, lifting Oracle's market cap close to $900 billion.",
      "media_url": null,
      "media_type": null,
      "media_description": null,
      "media_credit": null,
      "media_thumbnail": null,
      "language": "en",
      "sentiment": {
        "pos": 0.089,
        "neg": 0.011,
        "neu": 0.9
      },
      "source": {
        "id": "cnbc",
        "country": "US",
        "political_leaning": "center",
        "reliability_score": 8.0,
        "type": "mainstream_news"
      }
    }
  ]
}

Performance Comparison

The fields parameter can significantly reduce payload size. Here are typical examples based on actual API responses:

• Full response (all fields): ~1.5-2.5 KB per article
• Minimal response (title,article_link): ~0.2-0.4 KB per article
• Standard feed (title,description,pub_date,source_title,article_link): ~0.6-1.0 KB per article

For a request returning 50 articles:

• Full: ~75-125 KB
• Minimal: ~10-20 KB (80-85% reduction)
• Standard feed: ~30-50 KB (60-65% reduction)

These reductions directly translate to faster load times and lower bandwidth usage.

Best Practices

• Request only what you need: Always start by identifying the minimum fields required for your use case.
• Use progressive loading: Request minimal fields initially, then fetch full details only when users click for more.
• Consistent field lists: Use the same field list across your application for better caching.
• Include descriptive fields: For user-facing features, include title and description for better context.
• Keep article_link: Always include article_link so users can access the full article.
• Test performance: Measure the impact of different field combinations on your application’s performance.
• Combine with per_page: Use both fields and appropriate per_page values to optimize pagination.
• Cache strategically: Smaller payloads make client-side caching more efficient.

Common Use Cases

Headline Feed

fields=title,pub_date,article_link

What it is: A minimal news feed showing just headlines with timestamps and links.

Why use these fields: This is the leanest possible response for displaying breaking news or updates. Perfect when you need to show many headlines quickly without descriptions. The small payload size makes this ideal for real-time feeds, mobile notifications, or sidebar widgets where screen space is limited.

Ideal for: RSS-style feeds, push notification systems, quick news scanners, mobile apps with limited bandwidth

News Dashboard

fields=title,description,pub_date,source_title,article_link

What it is: A balanced feed with headlines, summaries, publication info, and source attribution.

Why use these fields: This combination gives users enough context to decide if they want to read more. The description field provides a summary, while source_title helps users evaluate credibility. This is the most common use case for news applications.

Ideal for: Main application views, news aggregators, content discovery platforms, news websites

Visual Feed

fields=title,media_url,media_type,article_link,pub_date

What it is: An image-focused feed emphasizing visual content over text.

Why use these fields: When visual appeal is your priority, these fields give you everything needed to create a gallery or card-based layout. The media_url and media_type fields let you filter and display images or videos, while title provides context. Skip the description to keep payloads small while maintaining visual impact.

Ideal for: Image galleries, Pinterest-style layouts, visual news feeds, social media apps

Link Extraction

fields=title,article_link

What it is: The absolute minimum data needed to create a clickable link.

Why use these fields: When you only need to collect URLs for archiving, indexing, or passing to other services, this ultra-minimal response is fastest. Perfect for building sitemaps, link databases, or feeding other processing pipelines where you’ll fetch full content later.

Ideal for: Web scrapers, bookmark services, content indexing systems, SEO tools

Source Analysis

fields=title,pub_date,source_title,article_link

What it is: A feed focused on tracking which sources are publishing what and when.

Why use these fields: When analyzing media coverage patterns, source diversity, or publication timing, these fields give you the essential metadata without article content. Useful for media monitoring, competitive intelligence, or studying how stories spread across outlets.

Ideal for: Media monitoring dashboards, source tracking tools, competitive analysis, journalism research

Common Errors and Tips

• Invalid field names: If you request a field that doesn’t exist, the API will ignore it and return only valid fields. Check the API documentation for the complete list of available fields.
• Whitespace handling: Spaces around commas are trimmed automatically, so fields=title, pub_date works the same as fields=title,pub_date.
• Always includes id: The id field is always returned regardless of your field list, as it’s required for pagination and reference.
• Nested source object: The source field returns the entire source metadata object. You cannot request specific subfields like source.political_leaning.
• Empty field parameter: If you pass an empty fields parameter, all fields are returned (same as omitting the parameter).

FAQ

• What is the fields parameter in NewsDataHub?
  • A comma-separated list of field names that controls which article properties are returned in the API response. The id field is always included regardless of your selection.
• Can I request nested fields from the source object?
  • No. The source field returns the complete source metadata object. You cannot select individual properties like source.political_leaning or source.country.
• Does using fields affect billing or rate limits?
  • No. Rate limits and billing are based on the number of API requests, not the response size. However, using fields reduces bandwidth and improves performance.
• What happens if I request a field that doesn’t exist?
  • The API ignores invalid field names and returns only the valid fields you requested, plus id. No error is returned.
• Which endpoints support the fields parameter?
  • All three news endpoints support fields: GET /v1/top-news, GET /v1/news, and GET /v1/news/{article_id}/related.
• What is NewsDataHub API?
  • NewsDataHub is a developer‑focused news API that aggregates and normalizes global coverage from mainstream, digital‑native, and specialty publishers. We ingest over 150,000 articles daily and support boolean search, rich filters (topic, source, language, country, political_leaning, source_type), cursor‑based pagination, and REST endpoints like /v1/top-news and /v1/news. Authentication is via API key in the X-API-Key header.
• How can I try your service?
  • Start with our free tier by signing up to get an API key, then test queries without code using the Interactive API Sandbox. When you’re ready, switch the same calls into your app with curl, JavaScript fetch, or your preferred HTTP client.

Further Reading

• NewsDataHub Political Leaning Filter Guide — Filter news by source bias to build balanced feeds and compare coverage across the political spectrum.
• Advanced Search & Filtering Guide — Master boolean search, combine multiple filters, and build complex queries.

Stay Updated

Subscribe to our newsletter to get technical insights, product updates, and behind-the-scenes notes on building NewsDataHub.

Subscribe to Newsletter

Olga S.

Founder of NewsDataHub — Distributed Systems & Data Engineering

Connect on LinkedIn