> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hirednow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

> Learn how to filter and sort results using date ranges and parameters

# How filtering works

## Learn how to filter and sort results using date ranges and parameters.

The API supports filtering results using various query parameters. You can filter by date ranges, sort order, and combine multiple parameters to get exactly the data you need.

## Common filtering examples

### All data for a campaign in descending order (most recent first)

To retrieve all campaign results sorted by the most recent first, pass the `sort` parameter with the value `desc`. This is ideal for displaying the latest results at the top of your dashboard or reports.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `sort=desc` - Sort results in descending order (newest to oldest)

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d sort=desc
  ```
</CodeGroup>

### All data for a campaign in ascending order (oldest first)

To retrieve all campaign results sorted from oldest to newest, pass the `sort` parameter with the value `asc`. This is useful for processing historical data chronologically or performing incremental syncs.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `sort=asc` - Sort results in ascending order (oldest to newest)

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d sort=asc
  ```
</CodeGroup>

### Data before a specific date

To get all results up to a certain date, use the `end_date` parameter. This will return all data from the beginning up to and including the specified date. Combine with `sort=desc` to see the most recent data within that range first.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `end_date=2024-01-01` - Return data up to and including January 1, 2024
* `sort=desc` - Show most recent results first within the date range

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d end_date=2024-01-01 \
    -d sort=desc
  ```
</CodeGroup>

### Data after a specific date

To get all results from a specific date onwards, use the `start_date` parameter. This will return all data from the specified date through the current date. Perfect for getting recent data or data since a last sync point.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `start_date=2024-06-01` - Return data from June 1, 2024 onwards
* `sort=desc` - Show most recent results first

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-06-01 \
    -d sort=desc
  ```
</CodeGroup>

### Data between two dates in descending order

To get results for a specific date range with the most recent first, use both `start_date` and `end_date` parameters along with `sort=desc`. This is ideal for generating reports for a specific time period.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `start_date=2024-07-01` - Start of the date range (July 1, 2024)
* `end_date=2024-09-30` - End of the date range (September 30, 2024)
* `sort=desc` - Show most recent results first within the range

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-07-01 \
    -d end_date=2024-09-30 \
    -d sort=desc
  ```
</CodeGroup>

### Data between two dates in ascending order

To get results for a specific date range in chronological order, use both `start_date` and `end_date` parameters with `sort=asc`. This is useful for processing data sequentially or building time-series visualizations.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `start_date=2024-07-01` - Start of the date range (July 1, 2024)
* `end_date=2024-09-30` - End of the date range (September 30, 2024)
* `sort=asc` - Show oldest results first within the range

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-07-01 \
    -d end_date=2024-09-30 \
    -d sort=asc
  ```
</CodeGroup>

## Advanced filtering examples

### Month-end reporting

For comprehensive monthly reports, combine date range filtering with a higher result limit. Set both `start_date` and `end_date` to the first and last day of the month, use `sort=desc` to show recent activity first, and increase the `limit` to retrieve more results per page.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - The specific campaign to retrieve results for
* `start_date=2024-09-01` - First day of the month (September 1, 2024)
* `end_date=2024-09-30` - Last day of the month (September 30, 2024)
* `sort=desc` - Show most recent results first
* `limit=100` - Retrieve up to 100 results per page (default is 10)

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-09-01 \
    -d end_date=2024-09-30 \
    -d sort=desc \
    -d limit=100
  ```
</CodeGroup>

### Incremental data sync

For syncing new data since your last fetch, filter by a specific campaign and start date. Use `sort=asc` to process results chronologically, starting from your last sync point. The higher limit ensures you can fetch more data in a single request.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - Filter to a specific campaign
* `start_date=2024-10-20` - Only fetch data from October 20, 2024 onwards
* `sort=asc` - Process data chronologically from oldest to newest
* `limit=100` - Fetch more results per page to reduce number of API calls

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-10-20 \
    -d sort=asc \
    -d limit=100
  ```
</CodeGroup>

### Single day's data

To retrieve all results for a specific day, set both `start_date` and `end_date` to the same date. This is useful for daily reports or investigating activity on a particular date. Combine with `campaign_id` to narrow down to a specific campaign.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - Filter to a specific campaign
* `start_date=2024-10-15` - Target date (October 15, 2024)
* `end_date=2024-10-15` - Same as start\_date to get only this day's data

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d start_date=2024-10-15 \
    -d end_date=2024-10-15
  ```
</CodeGroup>

### Data after a certain record

To retrieve results after a specific record, use the `starting_after` parameter with the last records `order_index` value with `sort=asc`. This is useful when you want to continue fetching data from where you left off.

**Parameters:**

* `campaign_id=123e4567-e89b-12d3-a456-426614174000` - Filter to a specific campaign
* `starting_after=1729612800000` - Fetch results after this record
* `limit=50` - Number of results to return per page

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.external.hirednow.ai/v1/campaigns/session/results \
    -H "Authorization: Bearer <YOUR_API_KEY>" \
    -d campaign_id=123e4567-e89b-12d3-a456-426614174000 \
    -d starting_after=1729612800000 \
    -d sort=asc \
  ```
</CodeGroup>

## Parameters

<ParamField query="sort" type="string" default="asc">
  Sort order for results. Use `asc` for ascending order (oldest first) or `desc`
  for descending order (most recent first).
</ParamField>

<ParamField query="start_date" type="string">
  Filter results to include only data from this date onwards. Format:
  `YYYY-MM-DD`
</ParamField>

<ParamField query="end_date" type="string">
  Filter results to include only data up to and including this date. Format:
  `YYYY-MM-DD`
</ParamField>

<ParamField query="campaign_id" type="string">
  Filter results to a specific campaign by providing the campaign UUID.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  A limit on the number of objects to be returned. Limit can range between 1 and
  100, and the default is 20.
</ParamField>

<ParamField query="starting_after" type="integer">
  A cursor for use in pagination. This is a big integer value that returns
  results after this cursor. Use this to continue fetching data from where you
  left off in a previous request.
</ParamField>

## Tips

* Combine `start_date` and `end_date` to get data for a specific date range
* Use `sort=desc` for the most recent data first, which is useful for dashboards and reporting
* Use `sort=asc` for incremental syncs to process data in chronological order
* Set `start_date` and `end_date` to the same value to get data for a single day
* Use `starting_after` for cursor-based pagination to efficiently fetch large datasets in batches