# Time Fields

Every job in the Fantastic.jobs API exposes up to three time fields. Each captures a different moment in the job's lifecycle, and which one you filter on materially changes which jobs you see.

## Quick reference

- **`date_posted`** - when the source site says the job was posted. May be earlier than `date_created`, and is occasionally null. Use this for "newly published" filters that match what end-users see on the source.
- **`date_created`** - when our system first indexed the job. Always populated, monotonically increasing. Use this for incremental syncs.
- **`date_modified`** - when a tracked field on the listing last changed upstream (title, description, location, salary, apply URL, ...). Only available on `modified-ats`.

All timestamps are UTC.

## Ingestion delay

There is a **1 to 2 hour** ingestion delay between a job being published on the source site and appearing in this API. The `1h` and `24h` `time_frame` parameters serve jobs with a one-hour enrichment delay (UTC):

- `1h` - if you call the endpoint at 09:15, you receive all jobs indexed between 07:00 and 08:00.
- `24h` - if you call the endpoint on 2026-01-02 at 09:15, you receive all jobs indexed between 2026-01-01 07:00 and 2026-01-02 08:00.

In practice this means `date_created` is always at least one hour behind real time when you query it. To avoid duplicates between calls, query the `1h` window every hour or the `24h` window at the same time every day - see [Recommended Strategy](/documentation/recommended-strategy).

## When to use `date_posted` vs `date_created`

- Use **`date_created`** for **incremental syncs**. Because it's monotonically increasing and always populated, querying with `date_created_gte=<last_run_timestamp>` is the safest way to fetch only new rows since your last call without missing any.
- Use **`date_posted`** for **"posted in the last X days" filters that should mirror what users see on the source site**. For example, if you're surfacing "jobs posted this week" to your end-users, `date_posted_gte` is the field that matches their mental model.

A job's `date_posted` can sit earlier than `date_created` - for example, a job we just discovered today that the source claims was posted three days ago - so the two fields will diverge during backfills or whenever a new source/ATS is added.

## `date_modified` (Modified Jobs)

`date_modified` is only available on `modified-ats`. The endpoint contains jobs whose tracked fields changed in the last 24 hours, typically 100,000 to 150,000 jobs per day.

- Call this endpoint at the same time once per day to get all recently modified jobs without duplicates.
- Some ATS modify the job's posted date very frequently. For those, we require the new `date_posted` to be older than 14 days before treating it as a modification.
- The response includes a `modified_fields` array listing which fields changed alongside `date_modified` itself.

Use this endpoint to keep an existing copy of the dataset in sync without re-fetching the full feed.