API DOCUMENTATION / TIMESTAMPS AND CURRENTNESS
Timestamps and currentness
Interpret source dates, observation dates, projection timestamps, and currentness without implying a refresh SLA.
Each timestamp answers a different question
| Field | What the source field represents |
|---|---|
source_posted_at | Timestamp attributed to the source posting; it can be null. |
first_seen_at / job_first_seen_at | Observation timestamps at posting or combined-job level. |
last_completed_fetch_at | Last completed fetch timestamp on a posting, nullable. |
curated_at | Projection curation timestamp on the combined job. |
job_updated_at | Combined-job update timestamp used in jobs list ordering. |
Currentness and stale are published flags
currentness may be current, uncertain, or not_current; stale is a separate boolean. The API reader returns published projection values. This source review does not establish how upstream assigns them, a stale threshold, or whether a live projection is current.
No refresh interval is established
The inspected API contract does not establish source refresh cadence, propagation delay, or a freshness SLA. Choose timestamps based on the product question and confirm operating expectations separately.
Use explicit time boundaries
Date filters require RFC 3339 values with a timezone. Usage-report periods specifically use UTC-Z timestamps and a from-inclusive, to-exclusive interval. Jobs filters use each parameter’s own timestamp parser; the usage-report interval rules apply to usage reports.
Which date to filter on
Each date filter reads a different field. Pick the one that matches your question.
| You want | Filter | Field it reads |
|---|---|---|
| Jobs the employer published in a period | posted_since, posted_until | postings[].source_posted_at, the date the source says the posting was published. It can be null; a job without one does not match. |
| Jobs that are new to Headcount Labs | first_seen_since, first_seen_until | job_first_seen_at, when any posting of the job was first collected. |
| Everything that changed since your last pull | updated_since, updated_until | job_updated_at, when the job record last changed. For ongoing sync, the changes feed is better. |
| Jobs that entered the final dataset in a period | curated_since, curated_until | curated_at. |
| Jobs whose source was read recently | last_fetch_since, last_fetch_until | postings[].last_completed_fetch_at, when the posting's source was last read completely. |
| Jobs you can still apply to | application_check=available, application_check_since | postings[].latest_application_check, the result and time of the latest application check. |
Dates take an RFC 3339 timestamp with a time zone (2026-09-21T00:00:00Z) or a plain date (2026-09-21). For posted_since a plain date means the start of that day in UTC; for posted_until it means the end of that day in UTC.
Common choices: a job board showing new openings uses posted_since; a pipeline that must not miss anything uses the changes feed; a check of what is still open uses the default currentness=current with application_check=available.
Continue in the reference
Check related request behavior before you build.
View route status and methods Discuss API requirements