Breaking Change: Enforcement of URL length limit for API requests

1157 4
Showing results for 
Search instead for 
Did you mean: 
Airtable Employee
Airtable Employee

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 "[{baseId}/{tableIdOrName}?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29](" \
-H "Authorization: Bearer YOUR_API_KEY"

Would become:

curl -X POST "{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 "[{baseId}/{tableIdOrName}?filterByFormula=SEARCH%28%22value%22%2C%7BField%20Name%7D%29](" \
-H "Authorization: Bearer YOUR_API_KEY"

Might become:

curl -X GET "{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 with your questions as well.


4 Replies 4

Thank you for posting this. I stumbled on the documentation earlier and wondered why it hadn’t been announced.

Being able to list records with a POST is a very nice feature, as sometimes constructing a POST body is easier than constructing query parameters.

Any insights on the two parameters that cannot be put in the post body and must be in the query parameters? (Why these exceptions, and will they eventually be accepted in the body?)

@James_Moody Thanks for alerting us to this! This actually makes things much easier for everyone, even people who aren’t going over the 16,000 character URL limit.

Hi @kuovonne! The two parameters you mentioned, timeZone and userLocale, are used by a few other parts of our infrastructure that currently rely on these values remaining as query parameters and the conversion is a bit less straight-forward compared to the other supported params.

We don’t have an exact timeline for this just yet, but we do intend to have complete parity between the GET and POST endpoints once we’re able to safely make the more nuanced changes required for timeZone and userLocale. Let me know if you have any other questions!

Thank you for the explanation! And also thank you for releasing this feature even without complete feature parity! And finally, thank you for letting us know the future plans!