- 08 Aug 2023
- 4 Minutes to read
Airtable Web API - Using filterByFormula or sort parameters
- Updated on 08 Aug 2023
- 4 Minutes to read
Learn how to filter or sort the results of an API response.
|Plan availability||All plan types|
Token-based access - In order to make API requests, you'll need to authenticate using one of the methods outlined here.
Filtering records in API requests
There are two different ways to filter records in API requests:
- One way to filter records is to pass a view parameter in an API request containing the list records scope, yielding only the records as they appear in a specific table view. The link above contains more details about how to pass the view parameter in a request.
- An alternative way to filter records in a call containing a list records scope is to use the
filterByFormulaparameter which we will outline in more detail below.
When filtering an API response using the
filterByFormula parameter, a valid formula must be used which will evaluate each record. This formula will need to be included in the table of the base where the API call is being requested.
To help demonstrate this, let’s say you have a table of ice cream flavors:
Including a list records scope in an API request to this table without any parameters will return all the flavors. Now, let’s say we only want to return flavors with 5-star ratings using the
The first step is to create a formula field in the table containing flavors that can evaluate whether the flavor has a 5-star rating in the "Rating" field. In this example, a simple formula could be used (Rating = 5) that performs a boolean true/false output, but your actual use case may involve more complexity.
As you can see below, the formula entered is working correctly – only “Cookies & Cream” and “Cookie Dough” have a value of ‘1’, because they are the only flavors that have 5 stars. We can now be confident that if we use this formula as our
filterByFormula parameter, it will return the appropriate values over time.
Next, you will need to add the formula to the
filterByFormula parameter in your request.
You should now have an encoded URL which will look something like this:
You can now test the request in a tool like Postman. In the test shown below, you can see that only ‘Cookies & Cream’ and ‘Cookie Dough’ were returned:
- If the response does not filter for the expected records, we recommend double-checking the formula in the Airtable base first to ensure it is returning the expected values in the formula field of the records you were expecting would be filtered.
- Any records that appear as
#Error!in the formula, then the output will not be included in the response.
- If the filterByFormula parameter is combined with the view parameter, only records in that view that satisfy the formula will be returned.
Sorting records in API requests
There are two different ways to sort records in API requests:
- One way to sort records is to pass a view parameter in an API request containing the list records scope, yielding the records in the API response in the order that they appear in a specific table view. The link above contains more details about how to pass the view parameter in a request.
- A second way to filter records in a List records request is to use the sort parameter. We'll cover the general steps for this below.
Using the ice cream flavors table example used above, it's possible you may want to return the flavors in order of highest to lowest rated:
First, you will need to create an encoded URL to use in your API request. Similar to
filterByFormula above, you can use this tool to encode a URL with a sort on the “Rating” field, with the direction of “desc”. It will look something like this:
You will then need to add the encoded URL as an object in the sort parameter of your API request.
You can now test the request with a tool like Postman to see if the parameter worked, the records returned are ordered by rating, highest to lowest:
No. You can only use field names. We recommend using field descriptions to call out the implications of changing any field names being used in API calls.
It may not be a valid formula – we recommend checking the formula by adding it to a field in the Airtable grid. This will help confirm what values the formula would be expected to filter.