Hi! I’m James, an engineer on the API team. Today I’m sharing an update as part of our API infrastructure changes that could affect your API usage, along with some action items that might be relevant.
We’ll be implementing a 16,000 character limit on the URL length of requests made to list table records using the public REST API. Once the limit is enforced, requests to this endpoint that exceed 16k characters will begin to fail.
Who is impacted?
From looking at past usage of our API, the vast majority of requests from users would not exceed or even come close to approaching this limit. We’ve used this data to identify and reach out directly to users who would be potentially affected, but if you currently have a workflow that involves making requests that meet this criteria, or plan to within the next few months, you will need to migrate to one of the suggested alternatives.
What do I need to do?
If your workflow involves making these requests using Airtable.js, we have already made the change to address this with the latest version. In order to take advantage of this, you’ll just need to update the version you are using to 0.11.5.
To prevent any interruption to your workflows, below are two alternatives you can leverage ahead of the limit enforcement (you can find more details on each approach in this support article)
Using POST instead of GET
We’ve created a new POST version of the existing list table records endpoint. This allows you to pass the same options as JSON in the request body that you normally would pass using query parameters. This will greatly reduce the overall URL length since these parameters will no longer need to be included in the URL itself.
For example, the following request:
curl -X GET "[https://api.airtable.com/v0/{baseId}/{tableIdOrName}?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29](https://api.airtable.com/v0/%7BbaseId%7D/%7BtableIdOrName%7D?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29)&maxRecords=20" \
-H "Authorization: Bearer YOUR_API_KEY"Would become:
curl -X POST "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/listRecords" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"filterByFormula": "SEARCH(\"value\",{Field Name})",
"maxRecords": 20
}'Again, if you use the Airtable.js library to access your base data, you’ll just need to update to v0.11.5 which includes changes to automatically use the POST endpoint for these requests when the URL length would otherwise exceed this limit.
Using a Filtered View
In many instances, the use of filterByFormula while listing table records via the API can greatly increase the overall length of the request URL once encoded. You can potentially reduce this length by creating a separate view of the table that includes all of the same filtering you would normally pass using query parameters. From there, you can pass the resulting viewId instead to return the same results via the API.
For example, the following URL:
curl -X GET "[https://api.airtable.com/v0/{baseId}/{tableIdOrName}?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29](https://api.airtable.com/v0/%7BbaseId%7D/%7BtableIdOrName%7D?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29)&maxRecords=20" \
-H "Authorization: Bearer YOUR_API_KEY"Might become:
curl -X GET "https://api.airtable.com/v0/{baseId}/{tableIdOrName}?view={viewId}" \
-H "Authorization: Bearer YOUR_API_KEY"Where the View referenced by viewId already has the filtering applied.
Where can I go to learn more?
Feel free to respond with any questions you may have about making the change to one of these alternatives. You can also reach out to support@airtable.com with your questions as well.
Thanks!
