How to filter news by date range#

To limit results to a time window, add the published_at.start and published_at.end parameters to your request. Both bounds are inclusive, and either one can be left off to leave that side of the range open. This request returns articles published in January 2024:

curl "https://api.apitube.io/v1/news/everything?published_at.start=2024-01-01&published_at.end=2024-01-31&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. Dates without a time zone are read as UTC midnight, so 2024-01-01 means 2024-01-01T00:00:00 UTC.

What parameters set a date range?#

APITube has three optional date parameters, and they all accept the same value formats:

• published_at.start — the earliest publication date to include (inclusive).
• published_at.end — the latest publication date to include (inclusive).
• published_at — a single day. The API returns every article published during that whole 24-hour day, from 00:00:00 up to the same time the next day.

Use start and end together for a window, or pass just one of them for an open-ended search. Sending only published_at.start means “from this date onward”, and only published_at.end means “up to this date”.

curl "https://api.apitube.io/v1/news/everything?published_at.start=2024-06-01&api_key=YOUR_API_KEY"

Which date formats are accepted?#

published_at.start, published_at.end and published_at all accept absolute dates in several formats:

• 2024-12-25 — YYYY-MM-DD
• 2024-12-25T10:30:00Z — ISO 8601 with time, in UTC
• 2024-12-25T10:30:00+03:00 — ISO 8601 with a time-zone offset
• 25-12-2024 — DD-MM-YYYY
• 25.12.2024 — DD.MM.YYYY
• 1735084800 — a Unix timestamp in seconds

Each value must be between 1 and 30 characters long. A YYYY-MM-DD date with no time is anchored to midnight UTC.

How do I use relative dates like the last 7 days?#

Instead of hard-coding a calendar date, you can pass a relative, Solr-style expression that APITube resolves at request time. This returns articles from the last 7 days:

curl "https://api.apitube.io/v1/news/everything?published_at.start=NOW-7DAYS&api_key=YOUR_API_KEY"

The supported relative forms are:

• NOW — the current moment.
• NOW-7DAYS, NOW+1MONTH — an offset before or after now.
• NOW/DAY, NOW/MONTH — rounded down to the start of that period, in UTC.
• NOW-1DAY/DAY — an offset combined with rounding (here, the start of yesterday).
• 7DAYS, 1WEEK, 2MONTHS — a bare amount, read as that long ago.
• 1w, 3d, 4h, 5y — short aliases for week, day, hour and year.

The available units are hours, days, weeks, months and years. So “everything since the start of this month” is published_at.start=NOW/MONTH, and “all of yesterday” is:

curl "https://api.apitube.io/v1/news/everything?published_at.start=NOW-1DAY/DAY&published_at.end=NOW/DAY&api_key=YOUR_API_KEY"

How do I sort articles within the range by date?#

Results are sorted by published_at in descending order — newest first — by default. To read the oldest matching articles first, add sort.order=asc — see how to sort news by relevance, date or quality for every ordering mode:

curl "https://api.apitube.io/v1/news/everything?published_at.start=NOW-30DAYS&sort.by=published_at&sort.order=asc&api_key=YOUR_API_KEY"

A date range combines with any other filter, so you can scope a feed to a time window and a language at once. For language filtering, see How to filter news by language. The full date syntax also lives in the canonical parameter reference.

Is there a maximum width for a date range?#

The range is unlimited unless the same request also searches article headlines. A request filtered by category.id, entity.id, source.domain, language.code, sentiment or any other non-headline parameter can span the whole archive in one call — published_at.start=2020-01-01 with no end date is a valid request.

Add a headline filter and a 31-day ceiling kicks in. The parameters that trigger it are title, title_starts_with, title_ends_with, title_pattern and the Boolean query. Three outcomes are possible:

Request	Result
Headline filter, no published_at dates at all	Runs against the last 31 days. HTTP 200 with warning ER0366 in meta.warnings and header x-query-window-clamped: 31
Headline filter, start and end 31 days apart or less	Runs exactly as written
Headline filter, range wider than 31 days	HTTP 400 with error ER0110

The open-ended form deserves care here, because it interacts with the ceiling in a way that is easy to miss: published_at.start=2024-01-01 on its own means “from that date until now”, so paired with a title filter it is a multi-year window and returns ER0110. Give an archive search an explicit published_at.end within the same month and it goes through.

# 200 — archive month, headline filter, window inside the ceiling
curl "https://api.apitube.io/v1/news/everything?title=inflation&published_at.start=2026-05-01&published_at.end=2026-05-31&api_key=YOUR_API_KEY"

The reason is cost: articles are stored partitioned by publication month, so the date range decides how much of the archive a headline search has to read, and a year-wide window reads nearly all of it. See how to search news by title for the headline-search side of this rule and the month-by-month pattern for longer periods.

Common Questions#

• Are the start and end dates inclusive?
• What does the single published_at parameter return?
• Can I leave one side of the range open?
• What error do I get for an invalid date?
• Does the 31-day ceiling apply to the single published_at parameter?

Are the start and end dates inclusive?#

Yes. An article published exactly on published_at.start or published_at.end is kept in the results — the filter uses inclusive bounds on both ends.

What does the single published_at parameter return?#

published_at=2024-12-25 returns every article published during that day, from 2024-12-25T00:00:00 up to 2024-12-26T00:00:00. Use it when you want one specific calendar day rather than a range built from start and end.

Can I leave one side of the range open?#

Yes. Send only published_at.start for “from this date onward”, or only published_at.end for “up to this date”. The bound you omit stays open, so the other limit alone decides the results. One exception: if the request also filters headlines, an open published_at.start older than 31 days exceeds the search-window ceiling and returns ER0110. An open published_at.end is always safe — the missing start is filled in 31 days before it.

What error do I get for an invalid date?#

A value that is not a recognized format returns HTTP 400 with an error code: ER0104 for a bad published_at.start, ER0106 for published_at.end, and ER0109 for published_at. Correct the value to one of the supported formats and retry.

Does the 31-day ceiling apply to the single published_at parameter?#

No. published_at=2024-12-25 selects one calendar day, which is already inside the ceiling, so it is never rejected and never triggers the ER0366 warning — even together with a headline filter. Use it whenever you want a specific day of the archive searched by headline: title=inflation&published_at=2024-12-25 is a valid request no matter how old the date is.