TikTok date windows that return nothing, and why

The convention, and the exception

Nearly every API that filters by date uses since for the earlier bound and until for the later one. It reads like English: since January, until March.

TikTok Profile Scraper does the opposite, and it does it consistently. Its input schema describes until as returning posts newer than the date, and since as returning posts older than it.

That is not a typo in one place. The input table says the same thing, and so does the listing’s own worked example:

{
  "usernames": ["gordonramsayofficial"],
  "until": "2025-01-01",
  "since": "2025-03-31",
  "maxItems": 500
}

The listing describes that run as returning posts published between January 1 and March 31. So until is the floor and since is the ceiling.

Why it fails silently

A swapped pair does not produce an error. It produces a window with a negative width: everything newer than March 31 and older than January 1, which is nothing.

The run succeeds. The dataset is empty. Nothing in the output says the filter was the problem, and the obvious conclusion is that the account has been quiet, which is wrong.

The check that takes ten seconds

Before you debug anything else, drop the date fields entirely and re-run with a small maxItems. If posts come back, the dates were the problem. If they do not, the problem is upstream: the profile may be private, deleted, or below the ten-post minimum the listing sets as a condition of use.

run_input = {"usernames": ["gordonramsayofficial"], "maxItems": 10}
# posts here but none with dates set  ->  the window was inverted

The other empty-dataset cause

While you are here, the second most common way a TikTok profile run comes back looking empty is maxItems. It caps the entire run rather than each profile, so a batch of ten handles under a ceiling of 100 shares those hundred posts. The first handle looks complete and the rest look silent.

Multiply the ceiling by the length of your list, or leave it empty and let the run take everything.

Worth writing once

Because the naming is counterintuitive, the safest thing is to never type these field names directly in application code. Wrap them:

def window(oldest=None, newest=None):
    """Reads in the normal direction; writes in the actor's."""
    out = {}
    if oldest: out["until"] = oldest   # yes, until is the older edge
    if newest: out["since"] = newest
    return out

One comment in one place beats remembering an inversion every time somebody touches the pipeline.