---
title: "Filtering API requests"
canonical: "https://support.appfire.com/space/FD/1802338375/Filtering%20API%20requests"
format: markdown
---
> Macro (aura-html)

The Flow API is built using the Django REST Framework and supports basic and enhanced filtering options. Most operators are supported. Learn more about [Django REST framework (external site, opens in new tab)](https://www.django-rest-framework.org/api-guide/filtering/).

## Basic filter options

Flow filters using standard REST syntax using the object ID.

For example, to obtain a specific user record, you would submit the following request:

`https://<workspace>.appfireflow.com/v3/customer/core/users/?id=1234567890`

Where `1234567890` is the specific user** **`ID` being requested.

### Field inclusion and omission

The API provides a mechanism to limit the fields returned for a given object using the `fields` and `omit` keywords. This can help with performance and limit the scope of data sent to the client application.

#### Fields keyword

To limit the response to a specific set of fields, use the `fields` keyword and provide a comma-separated list of field names.

Here’s an example:

`https://<workspace>.appfireflow.com/v3/customer/core/users/?fields=id,name,email&limit=3`

This will return three user records with only the `id`, `name`, and `email` fields.

#### Omit keyword

To limit the fields to a select few, use the `omit` keyword and provide a comma-separated list of field names.

Here’s an example:

`https://<workspace>.appfireflow.com/v3/customer/core/users/?omit=email,teams`

This will return all fields in the **Users** endpoint with the `email` and `teams` fields omitted:

## Enhanced filter options

The Flow API offers basic and enhanced filtering options for filtering objects. These filter options greatly improve performance by returning exactly the objects you want.

There are several built-in filter options for searching.

### gt

Filters for records that are greater than the specified value.

**Example:** All commits where lines of `new_work` code is greater than 100000.

**Request**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?new_work__gt=100000`

### gte

Filters for records that are greater than or equal to the specified value.

**Example:** All commits where lines of `new_work` code greater is than or equal to 2695.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?new_work__gte=2695`

### lt

Filters for records that are less than the specified value.

**Example:** All commits where lines of `new_work` code is less than 10.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?new_work__lt=10`

### lte

Filters for records that are less than or equal to the specified value.

**Example:** All commits where lines of `new_work` code is less than or equal to one.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?new_work__lte=1`

### in

Filters for records that are in a list of specified values.

**Example:** Repository ID is in 337844.

**Request:**

`https:/<workspace>.appfireflow.com/v3/customer/core/commits/?repo_id__in=337844`

### icontains

A case-insensitive string containment test equivalent to ILIKE “%foo%” in SQL.

**Example:** Commit message that contains the word `progress`.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?message__icontains=progress`

### startswith

A case-sensitive search for records that start with the specified string.

**Example:** User name starts with `chris`.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/users/?name__startswith=chris`

### between

Filters for records that fall within the specified range of values. Because there is no explicit `between` filter, use `__gte` and `__lt` filters to create a between.

**Example:** Commits created between June 8, 2018 and June 15, 2018.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?author_date__gte=2018-06-08&author_date__lt=2018-06-15`

### equals

A case-sensitive exact string match.

**Example: **Repository vendor type is github.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/repos/?vendor_type=github`

### not equal to

A case-sensitive match for all records that are not an exact string match.

**Example:** Repository vendor type is not `github`.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/repos/?vendor_type!=github`

### remove_excluded

Filters for commits that are not excluded.

**Example: **All commits except those made by excluded users.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?remove_excluded=true`

### smart_dedupe

Excludes duplicate commits.

Flow ensures each unique commit is represented once and only once. Certain branching and merging activities can cause git to create multiple SHAs for the same work. This ensures you don’t double count.

**Example**: All commits, excluding duplicates.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?smart_dedupe=true`

### exclude_weekends

Filters for commits committed on weekdays.

**Example:** All commits except those created on a Saturday or Sunday.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?exclude_weekends=true`

### exclude_outliers

Filters for commits that have been marked as outliers. Learn more about [outliers](https://appfire.atlassian.net/wiki/spaces/FD/pages/1802535113).

**Example:** All commits that have been excluded due to outlier detection.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?exclude_outliers=true`

### exclude_blocked

Filters for commits that are not associated with blocked or unprocessed repos.

**Example:** Commits not from blocked repos.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?exclude_blocked=true`

### normalize_authors

Replaces all user IDs with their respective main alias record.

**Example**: All commits, with user IDs replaced by apex user IDs.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?normalize_authors=true`

### apply_default_filters

Applies the default set of filters: `smart_dedupe`, `exclude_outliers`, `exclude_pr_orphans`, `exclude_merge`, and `exclude_blocked`.

**Example:** All commits matching the default filters.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/?apply_default_filters=true`

## Customizing results

Filtering your requests helps restrict what data is reported, but the results you get can still be too sizeable to manage. Customizing your results helps keep the data concise.

### Ordering

Use ordering to alter the sort order and type of the results. Place a **-** in front of the parameter you are ordering by to get results in descending order.

**Example:** `&ordering=-id`

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/commits/fields=id,new_work,churn&limit=5&ordering=-id`

### Pagination

Flow uses limit and offset pagination options:

- `limit` — restricts the results to a specific number of data rows. For example, setting `limit` to 5 means that the system only returns the first five rows in the matching record set.
- `offset` — indicates where to start the results. A common practice is to combine this option with `limit`. For example, you could limit the request to only 50 records and specify an `offset` of 10, which would result in results of records 11 to 50.

> ℹ️ The maximum page size is 1,000. This is set by the `limit` parameter.

**Request:**

`https://<workspace>.appfireflow.com/v3/customer/core/users/?fields=id,name&ordering=name&limit=5`

The request with multiple options returns nice and clean results, but there are three important things about the response that should catch your attention:

- Although there is a count of 22598 records, the response shows only five records, as we requested.
- Instead of returning all user fields, the system has returned the two we wanted: `id` and `name`.
- The records are in alphabetical order since we specified order by name.