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.

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?

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.

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.