- Getting started with Airtable
- Introduction to Airtable basics
- Contacting Airtable Support Updated
- Airtable home screen
- Glossary of Airtable terminology
- Airtable technical requirements
- Feature differences between Airtable on desktop and mobile
- Airtable keyboard shortcuts
- Using Markdown in Airtable
- Adding descriptions in Airtable
- Finding Airtable IDs
- Airtable Automations
- Automations Overview
- Automation feature walkthroughs
- Integrated automation walkthroughs
- Airtable automation walkthroughs
- Linking existing records using automations
- Conditional groups of automation actions
- Repeating groups of Airtable automation actions
- Creating recurring records using automations
- How to delay Airtable automation runs
- Prevent automations from triggering by mistake
- Use automations to timestamp status updates
- Automation Triggers
- Airtable Triggers
- Airtable automation trigger: When record matches conditions
- Airtable automation trigger: When a form is submitted
- Airtable automation trigger: When record created
- Airtable automation trigger: When record updated
- Airtable automation trigger: When record enters view
- Airtable automation trigger: At scheduled time
- Airtable automation trigger: When webhook received
- Airtable automation trigger: When a button is clicked
- Airtable automation trigger: When email received Updated
- Integrated Triggers
- Airtable Triggers
- Automation Actions
- Airtable Actions
- Airtable automation action: Send email Updated
- Airtable automation action: Create record
- Airtable automation action: Update record
- Airtable automation action: Find records
- Airtable automation action: Sort list
- Airtable automation action: Run a script Updated
- Airtable automation action: Generate with AI
- Integrated Actions
- Airtable automation actions: Slack
- Airtable automation actions: Google Workspace
- Airtable automation action: Send MS Teams message
- Airtable automation actions: Outlook
- Airtable automation actions: Jira Cloud
- Airtable automation actions: Jira Server / Data Center
- Airtable automation actions: Salesforce
- Airtable automation action: Create post in Facebook Pages
- Airtable automation actions: GitHub Issues
- Airtable automation action: Hootsuite post
- Airtable automation action: Send Twilio SMS
- Airtable Actions
- Airtable Bases
- Using Airtable Cobuilder
- Airtable bases overview
- Creating and managing Airtable bases
- Structuring bases in Airtable
- Moving bases between workspaces in Airtable
- Creating and managing tables in Airtable
- Creating Airtable base share links
- Importing third-party data into Airtable
- Using insights in Airtable
- Troubleshooting Airtable base performance
- Airtable Betas
- Collaborating in Airtable
- Airtable Enterprise Support
- General Enterprise information
- External badging in Airtable
- Using app library and components in Airtable Updated
- Ask an Expert beta overview
- European data residency at Airtable
- Airtable user groups overview
- Airtable Enterprise API
- Creating and managing data retention policies in Airtable
- eDiscovery APIs in Airtable
- Airtable and data loss prevention
- Accessing Enterprise audit logs in Airtable
- Set up Jira Server / Data Center to connect with Airtable
- Admin panel pages
- Airtable admin panel overview
- Users - Airtable enterprise admin panel
- Airtable admin panel user details
- Groups - Airtable admin panel
- Workspaces - Airtable Enterprise Admin Panel
- Bases - Airtable admin panel
- Interfaces - Airtable admin panel
- Data sets - Airtable admin panel
- Managed apps - Airtable admin panel
- Components - Airtable admin panel
- Reports - Airtable admin panel
- Settings - Airtable admin panel Updated
- Managing Enterprise organizations
- Managing Enterprise admins in admin panel
- Using Organizations
- Organization branding for apps in Airtable
- Enterprise Hub in Airtable
- Enterprise Hub: Org unit assignment with user groups Updated
- Deactivating, removing access, and reactivating users in the admin panel
- Managing user access to workspaces and bases
- Airtable Enterprise Key Management Updated
- Custom terms of use New
- Enterprise SSO
- General Enterprise information
- Airtable Extensions
- Airtable Fields
- Fields Overview
- Attachment
- Date-based fields
- Formula
- Getting Started with Formulas
- Formula Foundations
- The essentials of Airtable formulas
- Formula writing tips for beginners
- Troubleshooting formulas
- Basic calculations
- Conditional statements
- Logical arguments
- Working with dates
- Displaying DATETIME_FORMAT using the date field in Airtable
- Working with date functions in Airtable
- Calculating the difference between dates in Airtable
- Supported DATETIME_DIFF unit specifiers in Airtable
- Supported DATETIME_FORMAT format specifiers in Airtable
- Using the DATETIME_PARSE() formula in Airtable
- Working with timezones
- Record functions
- Text functions
- Numeric functions
- Common Solutions: Beginner
- Common Solutions: Intermediate
- Common Solutions: Advanced
- Long Text Field
- Linked Record Field
- Linking records in Airtable
- Limiting linked record selection to a view in Airtable
- Dynamic filtering in linked record fields
- Linking to one, many, or a subset of Airtable records
- Converting existing fields to Airtable linked records
- Reordering record links in Airtable
- Understanding linked record relationships in Airtable
- Number-Based Fields
- Other Fields
- Rollup, lookup, and count fields
- Select and user fields
- Integrating with Airtable
- API
- Getting started with Airtable's Web API
- Creating personal access tokens
- Airtable Webhooks API Overview
- Service accounts overview
- Airtable Web API - Using filterByFormula or sort parameters
- Airtable API Deprecation Guidelines
- Airtable API: Common troubleshooting
- Managing API call limits in Airtable
- URL length limitations for web API requests
- Integration services
- Third-party integrations via OAuth overview
- Troubleshooting disconnected OAuth integrations in Airtable
- Options for integrating with Airtable
- Third-party integrations - Common troubleshooting
- Low-code integrations - Common troubleshooting
- Integrating Airtable with external calendar applications
- Visualizing records from Airtable in Tableau
- Visualizing Airtable records in Microsoft Power BI & Power Query
- Integrating HubSpot with Airtable
- Using Zapier to integrate Airtable with other services
- Using Zapier's Multi-Step Zaps to find and update records
- Using IFTTT to integrate Airtable with other services
- Integrating with AWS Lambda & DynamoDB
- Developer tools
- API
- Airtable Interface Designer
- Interface Designer overview articles
- Interface layouts
- Interface elements
- Adding and removing elements in interfaces
- Adding layouts to interfaces
- Formatting elements in interfaces
- Interface element: Button
- Interface element: Calendar
- Interface element: Chart
- Interface element: Filter
- Interface element: Gallery
- Interface element: Grid
- Interface element: Kanban
- Interface element: Number
- Interface element: Record picker
- Interface element: Text
- Interface element: Timeline
- Learning and Resources
- Managing Airtable
- Airtable Policy
- Airtable Records
- Airtable Sync
- Airtable Views
- Airtable Workspaces
- Print
- Share
- DarkLight
- PDF
Airtable Web API - Using filterByFormula or sort parameters
- Updated on 06 Aug 2024
- 4 Minutes to read
- Print
- Share
- DarkLight
- PDF
All plan types | |
Token-based access - In order to make API requests, you'll need to authenticate using one of the methods outlined here. |
Learn how to filter or sort the results of an API response.
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
filterByFormula
parameter 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:
![](http://cdn.airtable.document360.io/d0ee2ee4-3f78-47c7-b388-85e40be9fb89/Images/Documentation/api_filterbyformula_flavors_03222023.png)
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 filterByFormula
parameter:
Step 1:
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.
Step 2:
As seen 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.
Step 3:
Next, you will need to add the formula to the filterByFormula
parameter in your request.
Note
If you are not using our official Javascript client, Airtable.js, the formula must be encoded first before passing it as a value. You can use this tool to encode either the formula or the URL before using it in an API request.
Step 4:
You should now have an encoded URL which will look something like this: https://api.airtable.com/v0/{your_app_id}/Flavors?filterByFormula=Rating%3D5
Step 5:
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:
Filtering dependencies
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
0
,false
,NaN
,[]
, or#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, you may want to return the flavors in order of highest to lowest rated:
Step 1:
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:
https://api.airtable.com/v0/{your_app_id}/Flavors?sort%5B0%5D%5Bfield%5D=Rating&sort%5B0%5D%5Bdirection%5D=desc
Note
A value of "asc" could be used at the end of the formula instead of "desc" to sort the results in ascending order instead.
Step 2:
You will then need to add the encoded URL as an object in the sort parameter of your API request.
Step 3:
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:
![](http://cdn.airtable.document360.io/d0ee2ee4-3f78-47c7-b388-85e40be9fb89/Images/Documentation/api_sorting_postman_response_03232023.png)
Note
If combined with a view parameter, the sort parameter overrides the sorting of the view specified in the view parameter. If neither the sort nor the view parameter is included, the order of records is arbitrary.
URL Encoding
If you are not using our official Javascript client, Airtable.js, you will likely need to URL-encode your parameter values to get a valid URL. You can use our URL encoder to do this, by filling in your formula and other parameter values and copying the resulting URL:
FAQs
Can I use field IDs in my filterByFormula API call?
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.
Why isn’t my filterByFormula filtering correctly?
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.