Date, ID, and Age Slicing Parameters Documentation

Table of contents

The /api/jobs/ endpoint supports dedicated slicing parameters to retrieve exact subsets of job data by publication date, job ID range, and posting age. These parameters are useful for deterministic dataset windows, incremental updates, and efficient synchronization pipelines.

Endpoint Scope

• Endpoint: /api/jobs/
• Method: GET
• Primary use: deterministic dataset windows, incremental updates, and efficient sync pipelines

Query Scope Limits

To keep response times predictable as the job database grows, /api/jobs/ rejects query shapes that could require excessively broad database work. The limits apply to every request that reaches the Jobs endpoint, regardless of subscription tier or staff status.

• The effective published-date range cannot exceed 365 days.
• An explicit min_id and max_id range cannot exceed 10,000,000 IDs.
• The ID limit is calculated inclusively as max_id - min_id + 1.
• A date or age filter does not relax the ID limit. Both limits are checked independently.
• An unbounded historical query such as max_age=off without another lower published-date bound or a bounded ID range is rejected.
• page_size does not bypass these limits. It controls the response page size, not the size of the database work needed to determine the result set.

These limits make resource usage more predictable and prevent requests that would be likely to time out before returning useful results. Requests that exceed a limit return 400 Bad Request with a query_scope error.

The limits described here apply to /api/jobs/. They do not apply to /api/jobsexpired/, including requests using expired_since or expired_until.

Slicing Parameters

published_since

• Type: date string (YYYY-MM-DD)
• Behavior: includes jobs published on or after the given date
• Scope rule: when no earlier lower bound is supplied, the effective upper bound is today, so the range must be no more than 365 days

Example:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'published_since=2026-05-01'

published_until

• Type: date string (YYYY-MM-DD)
• Behavior: includes jobs published on or before the given date
• Scope rule: use it with a lower published-date bound or a numeric max_age; an upper bound by itself does not define a safe historical scope

Example:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'published_since=2026-05-01' \
  --data-urlencode 'published_until=2026-05-31'

min_id and max_id

• Type: integer
• Behavior: min_id includes jobs with id >= min_id; max_id includes jobs with id <= max_id
• Scope rule: when both are supplied, their inclusive span must be no more than 10,000,000 IDs, even if a date or age filter is also supplied
• Recommended use: send both values for deterministic incremental and backfill batches

Example of a range exactly at the limit:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'min_id=10000000' \
  --data-urlencode 'max_id=19999999'

If an incremental feed starts at watermark + 1, the largest matching upper bound is:

max_id = watermark + 10,000,000

If the feed starts at the watermark itself, use watermark + 9,999,999 instead, because both endpoints are inclusive.

A one-sided ID filter can be used when it is combined with a numeric age or a lower published-date bound. For deterministic synchronization, a bounded pair is still preferred. An ID-only request must include both min_id and max_id.

min_age

• Type: integer (days)
• Behavior: includes jobs at least N days old
• Scope rule: use it with a lower bound such as max_age or published_since; min_age alone leaves the historical lower boundary open

Example:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'min_age=14' \
  --data-urlencode 'max_age=45'

max_age

• Type: integer (days), or off, null, or 0 for non-access-lite plans
• Behavior: includes jobs published within the last N days
• Scope rule: a numeric value creates a lower published-date bound; the effective range must still be no more than 365 days

Example:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'max_age=180'

Disabling the age filter is allowed only when another safe scope is present:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'max_age=off' \
  --data-urlencode 'min_id=20000000' \
  --data-urlencode 'max_id=20999999'

Default Age-Window Behavior

When no slicing parameter is supplied, /api/jobs/ applies a default max_age=90 window.

For non-access-lite plans, if any slicing parameter is present, the implicit 90-day window is not added. This ensures that explicit date, ID, and age queries are not silently narrowed by the default age limit.

For access-lite plans, date, ID, and age slicing parameters are not available; access is restricted to the latest 90 days.

Combination Rules and Examples

Date range within the limit

This request covers 90 days and is accepted:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'published_since=2026-01-01' \
  --data-urlencode 'published_until=2026-03-31' \
  --data-urlencode 'page_size=4000'

ID range with an age filter

Both restrictions are checked. This request is accepted because its ID range is 10,000,000 IDs and its age window is 180 days:

curl -G 'https://jobdataapi.com/api/jobs/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'min_id=50000001' \
  --data-urlencode 'max_id=59999999' \
  --data-urlencode 'max_age=180'

The following request is rejected because the ID range is too wide, even though max_age=180 narrows the publication dates:

/api/jobs/?min_id=50000001&max_id=60000001&max_age=180

Incremental feed window

For a feed whose last successfully processed ID is watermark, request a bounded batch and advance the watermark only after all pages are stored:

min_id=watermark+1
max_id=watermark+10000000
max_age=180
page_size=100

The numeric age filter is optional for this pattern, but it can provide an additional freshness boundary. The ID range limit still applies.

Unbounded historical query

This request is rejected because disabling the age filter does not provide a safe lower boundary by itself:

/api/jobs/?max_age=off

Use an explicit date or ID scope instead:

/api/jobs/?max_age=off&published_since=2026-01-01

The second example is accepted only when the effective date range through today is no more than 365 days.

Overly broad date query

This request is rejected when the effective range is more than 365 days:

/api/jobs/?max_age=off&published_since=2024-01-01

Split historical work into smaller date windows or bounded ID ranges.

Error Handling

Check for 400 Bad Request before starting pagination. A scope validation failure has the following general shape:

{
  "query_scope": [
    "The job ID range cannot exceed 10,000,000 listings."
  ]
}

Do not retry the same request unchanged. Adjust the date or ID bounds, then start pagination again from page 1.

Expired Jobs Date Window

The /api/jobsexpired/ endpoint is separate from /api/jobs/ and is not affected by the 365-day published-date or 10,000,000-ID limits described above. It applies its own default 60-day expiration window when no slicing parameter is supplied.

Use expired_since and expired_until for explicit expiration windows:

curl -G 'https://jobdataapi.com/api/jobsexpired/' \
  -H 'Authorization: Api-Key YOUR_API_KEY' \
  --data-urlencode 'expired_since=2026-05-01' \
  --data-urlencode 'expired_until=2026-05-31' \
  --data-urlencode 'page_size=4000'

The expired-jobs endpoint is available to access pro subscribers and higher.

Plan and Access Rules

All plans except access lite

• Date, ID, and age slicing are supported when the subscription permits it.
• Numeric max_age values create a date lower bound.
• max_age=off, max_age=null, and max_age=0 require another safe scope.
• The query scope limits in this article still apply.

API access lite

• Access is restricted to the latest 90 days on /api/jobs/.
• The following parameters are not available:
• published_since
• published_until
• min_id
• max_id
• min_age
• max_age

Anonymous requests

• Anonymous requests cannot use date, ID, or age slicing parameters.
• Anonymous requests cannot request additional pages.

Efficiency Notes

• Use explicit date or ID boundaries for reproducible dataset slices.
• Split historical pulls into date windows no longer than 365 days, preferably much smaller when the result volume is high.
• Split ID work into ranges no wider than 10,000,000 IDs. Smaller ranges are recommended for incremental feeds and easier recovery.
• Use page_size up to 4000 for large pulls, but process each page sequentially and write results incrementally.
• Follow the returned next URL rather than synthesizing page URLs.
• Deduplicate by API job id when processing overlapping windows.
• Keep each window independently retryable and do not advance a sync checkpoint until all pages in the window have been stored successfully.
• Add a short date overlap or periodic reconciliation pass when late-arriving listings matter to your integration.

For complete job data downloads and large historical analytics workloads, consider the CSV and Parquet File Downloads Documentation.

Related Docs