Filtering content by date
The four date parameters, their precedence, and the limits.
Every request to content.list and content.statistics covers a time window. Four parameters define it: three set the start of the window, one sets the end.
A request with no date parameter covers the last 7 days. That default is the most common reason a search returns fewer posts than expected.
Every step shows the same call in all six Zelf clients and in cURL. Pick a language and the install line above the snippet switches with it. Each client reads your key from ZELF_API_KEY.
- 01The four parameters
- 02The default window
- 03A window relative to now
- 04A fixed window
- 05Precedence between the start parameters
- 06Combining posted_before with a relative window
- 07Measuring a window before paging it
- 08Periods longer than 366 days
The four parameters
posted_after, posted_within_hours and posted_within_days define the start of the window. posted_before defines the end. A value outside the ranges below returns VALIDATION_ERROR.
posted_aftertimestamp | Start of the window. Suits a window that must be identical on every run. |
|---|---|
posted_within_hoursinteger, 1 to 8760 | Start of the window, counted back from the current time. 8760 hours is one year. |
posted_within_daysinteger, 1 to 365 | Start of the window, counted back from the current time. Defaults to 7. |
posted_beforetimestamp | End of the window. Can be combined with any of the three above. |
Out-of-range values are rejected, not clamped. posted_within_days=400 returns VALIDATION_ERROR rather than being read as 365.
The default window
A request with no date parameter still has a window: the last 7 days. Every response reports the window it used in applied_filters, which is the first field to read when a search returns fewer posts than expected.
pip install zelf-sdkimport os
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
search="running shoes",
)
print(result){
"log_id": "0ca57078-d810-4038-a1d7-02953ac7ce60",
"applied_filters": {
"posted_within_days": 7,
"brand_id": null
},
"results": [],
"item_count": 0,
"page": 1,
"next": null,
"previous": null
}An empty result with posted_within_days: 7 in applied_filters usually indicates the window rather than the query. Widening the window comes before changing the search terms.
A window relative to now
posted_within_hours and posted_within_days are both counted back from the current time. posted_within_hours suits a period shorter than a day, such as a launch in progress; posted_within_days suits anything longer.
pip install zelf-sdkimport os
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
brand_id="brd_6u599tNI2jemKDcb",
posted_within_hours=6,
)
print(result)A fixed window
posted_after and posted_before take ISO 8601 timestamps and may sit anywhere in the available history. Together they suit a reporting period, where the window must be identical each time the query runs.
pip install zelf-sdkimport os
from datetime import datetime, timezone
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
brand_id="brd_6u599tNI2jemKDcb",
posted_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
posted_before=datetime(2026, 3, 31, 23, 59, 59, tzinfo=timezone.utc),
)
print(result)posted_after and posted_before may be at most 366 days apart. A longer period is read as consecutive requests.
Precedence between the start parameters
Three parameters define the same edge of the window, so a request may carry more than one. Such a request is valid. The API applies the first one present, in the order below, and ignores the rest. applied_filters reports only the parameter that was applied.
posted_afterapplied first | An explicit timestamp takes precedence over both relative parameters. |
|---|---|
posted_within_hoursapplied second | Applied when posted_after is absent. |
posted_within_daysapplied third | Applied when both parameters above are absent. |
posted_beforealways applied | Defines the end of the window, so it is not part of this order. |
pip install zelf-sdkimport os
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
brand_id="brd_6u599tNI2jemKDcb",
posted_within_hours=6,
posted_within_days=30,
)
print(result){
"applied_filters": {
"posted_within_hours": 6,
"brand_id": "brd_6u599tNI2jemKDcb"
},
"item_count": 12,
"page": 1
}posted_within_days is absent from applied_filters because it was not applied. That field identifies the window behind every response.
Combining posted_before with a relative window
With posted_before alongside posted_within_hours or posted_within_days, the window is counted back from posted_before rather than from the current time. The request below covers 2026-08-31T00:00:00Z to 2026-09-01T00:00:00Z.
pip install zelf-sdkimport os
from datetime import datetime, timezone
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
brand_id="brd_6u599tNI2jemKDcb",
posted_before=datetime(2026, 9, 1, tzinfo=timezone.utc),
posted_within_hours=24,
)
print(result)Measuring a window before paging it
content.list does not count the full result set: item_count is the number of rows on the returned page. content.statistics takes the same date parameters and returns post_count for the entire window, which sizes the set before it is paged.
pip install zelf-sdkimport os
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.statistics(
brand_id="brd_6u599tNI2jemKDcb",
posted_within_days=30,
)
print(result){
"applied_filters": {
"posted_within_days": 30,
"brand_id": "brd_6u599tNI2jemKDcb"
},
"results": [
{
"post_count": 1284,
"view_count": 9412335,
"like_count": 412908,
"unique_creator_count": 317
}
],
"item_count": 1
}Both endpoints apply these parameters identically, so one set of dates covers the same posts on each. An AI analysis created with the same window covers them as well.
Periods longer than 366 days
A single request covers at most 366 days. A longer period is read as consecutive requests, each window ending where the next begins. posted_after and posted_before anchor every window to a fixed date rather than to the current time.
pip install zelf-sdkimport os
from datetime import datetime, timezone
from zelf import ZelfAPIClient
client = ZelfAPIClient(api_key=os.environ["ZELF_API_KEY"])
result = client.content.list(
brand_id="brd_6u599tNI2jemKDcb",
posted_after=datetime(2025, 9, 1, tzinfo=timezone.utc),
posted_before=datetime(2026, 9, 1, tzinfo=timezone.utc),
)
print(result)A window wider than 366 days returns VALIDATION_ERROR on posted_after. Content posted before 2025-01-01 is not available.
Summary
| Step | Request | Input | Output |
|---|---|---|---|
| No date parameters | GET /api/v1/content/ | search or brand_id only | The last 7 days, reported in applied_filters |
| Relative, in hours | GET /api/v1/content/ | posted_within_hours, 1 to 8760 | Counted back from the current time |
| Relative, in days | GET /api/v1/content/ | posted_within_days, 1 to 365 | Counted back from the current time |
| Fixed window | GET /api/v1/content/ | posted_after and posted_before, at most 366 days apart | An identical window on every run |
| More than one start | GET /api/v1/content/ | Any combination | posted_after, then posted_within_hours, then posted_within_days |
| Size a window | GET /api/v1/content/statistics/ | The same date parameters | post_count for the entire window, not one page |