# Date, ID, and Age Slicing Parameters Documentation

Slice smarter, sync faster: precise dataset windows for the /api/jobs/ endpoint

---

The `/api/jobs/` endpoint supports dedicated slicing parameters to retrieve exact subsets of job data by publication date, job ID range, and posting age.

This page documents each slicing parameter in detail, including behavior, constraints, and practical query examples.

## Endpoint Scope

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

## Slicing Parameters

### `published_since`

- **Type:** date string (`YYYY-MM-DD`)
- **Behavior:** includes jobs published on or after the given date
- **Typical use:** start boundary for date-window extraction

Example:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?published_since=2026-05-01" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### `published_until`

- **Type:** date string (`YYYY-MM-DD`)
- **Behavior:** includes jobs published on or before the given date
- **Typical use:** end boundary for date-window extraction

Example:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?published_until=2026-05-31" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### `min_id`

- **Type:** integer
- **Behavior:** includes jobs with `id >= min_id`
- **Typical use:** lower boundary for deterministic ID-range batches

Example:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?min_id=2500000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### `max_id`

- **Type:** integer
- **Behavior:** includes jobs with `id <= max_id`
- **Typical use:** upper boundary for deterministic ID-range batches

Example:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?max_id=2599999" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### `min_age`

- **Type:** integer (days)
- **Behavior:** includes jobs at least N days old
- **Typical use:** age-based segmentation (for example, older inventory windows)

Example:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?min_age=30" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### `max_age`

- **Type:** integer (days), or disabling value (`off`, `null`, `0`) for non-**access lite** plans
- **Behavior:** includes jobs up to N days old
- **Typical use:** freshness windows (for example, latest 1-7 days)

Examples:

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?max_age=7" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?max_age=off" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

## Default Age-Window Behavior

On `/api/jobs/`, when no slicing parameter is supplied, a default age window is applied:

- default behavior: `max_age=90`

For non-**access lite**, if any slicing parameter is present (`published_since`, `published_until`, `min_id`, `max_id`, `min_age`, `max_age`), the default `max_age=90` is not auto-applied.

This ensures explicit date/ID/age slicing queries are not silently narrowed by the default age window.

## Plan and Access Rules

### All plans except API **access lite**

- Slicing parameters are supported.
- `max_age` can be disabled with `off`, `null`, or `0`.

### API access lite

- Restricted to latest 90 days on `/api/jobs/`.
- Date/ID/age slicing parameters are not available:
  - `published_since`
  - `published_until`
  - `min_id`
  - `max_id`
  - `min_age`
  - `max_age`

### Anonymous requests (no API key)

- Limited test access is available.
- Date/ID/age slicing parameters are not available.

## Combination Examples

### Exact date window (reporting period)

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?published_since=2026-05-01&published_until=2026-05-31&page_size=5000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### Deterministic ID-range batch (backfill)

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?min_id=2000000&max_id=2099999&page_size=5000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### Freshness window (recent updates)

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?max_age=2&page_size=1000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### Age band (targeted lifecycle slice)

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?min_age=14&max_age=45&page_size=5000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

### Full-history pull (non-**access lite**)

```bash
curl -X GET "https://jobdataapi.com/api/jobs/?max_age=0&page_size=5000" \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

## Efficiency Notes

- Use explicit boundaries (`published_since` + `published_until`, or `min_id` + `max_id`) for reproducible dataset slices.
- Use larger `page_size` values to reduce request count.
- For frequent updates, use small `max_age` windows (for example `1`, `2`, `3`) to reduce payload size.
- For large historical retrieval, use ID-range chunking and process sequentially.