Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt

Use this file to discover all available pages before exploring further.

​
What it does

The Search Airtable tool queries records in a specific table. It supports three query modes, all with offset-based pagination:
  1. Free-text search — pass a searchTerm + searchFields to match a case-insensitive substring across named fields (the tool builds an OR(SEARCH(...)) formula for you)
  2. Formula filter — pass a raw filterByFormula for full Airtable formula-language filtering (AND/OR logic, date math, linked-record filtering, etc.)
  3. Plain list — omit filters and just list records, optionally scoped to a view, with sort/fields/maxRecords applied

​
Key features

  • Three complementary query modes covering quick lookups through complex structured filters
  • Case-insensitive free-text search across any set of fields
  • Full Airtable formula language support for structured filters
  • Sort by one or more fields, ascending or descending
  • Scope results to a named view (honors the view’s own filter/sort)
  • Return only specific fields to keep responses small
  • Offset-based pagination via nextOffset

​
Parameters

ParameterTypeRequiredDescription
baseIdstringYesAirtable base ID (starts with app). Get from airtable_get_schema
tableIdOrNamestringYesTable ID (starts with tbl) or the table’s display name. IDs are more stable against renames
searchTermstringNoFree-text needle. Requires searchFields. Matched case-insensitively as a substring
searchFieldsstring[]NoField names to search within. Required when searchTerm is set
filterByFormulastringNoAirtable formula to filter records. Takes precedence over searchTerm. Example: "AND({Status}='Active', {Amount}>1000)"
fieldsstring[]NoSubset of field names to include in each record. If omitted, returns all fields
sortarrayNoArray of { field, direction? } sort rules. Applied in order (primary first)
maxRecordsintegerNoTotal records to return across pages (max 1000)
pageSizeintegerNoRecords per page (default 100, max 100)
viewstringNoView ID or name. When set, results honor the view’s filter/sort in addition to any passed here
offsetstringNoPagination cursor from a previous response’s nextOffset

​
Common use cases

​
Free-text find

baseId: "appXXXXXXXXXXXXXX"
tableIdOrName: "Contacts"
searchTerm: "acme"
searchFields: ["Name", "Company Name", "Email"]
Returns any contact whose name, company, or email contains “acme” (case-insensitive).

​
Structured filter with formula

tableIdOrName: "Deals"
filterByFormula: "AND({Stage}='Negotiation', {Close Date} > TODAY())"
fields: ["Name", "Amount", "Owner", "Close Date"]
sort: [{ "field": "Amount", "direction": "desc" }]
maxRecords: 25
Returns up to 25 future-dated negotiation deals, highest value first, with only the listed fields.

​
Scope to a view

tableIdOrName: "Tasks"
view: "My Team — Open"
maxRecords: 50
Returns records as the named view shows them — with whatever filter and sort the view defines.

​
Paginate a large table

First call: 
tableIdOrName: "Orders"
pageSize: 100
Subsequent calls: 
tableIdOrName: "Orders"
pageSize: 100
offset: "<value from previous response's nextOffset>"
Repeat until hasMore is false.

​
What you get back

  • records[] — each with id, createdTime, and a fields object keyed by field name
  • count — number of records in this response
  • hasMore — boolean indicating whether more records are available
  • nextOffset — opaque cursor to pass as offset on the next call (null when hasMore is false)

​
Best practices

  • Prefer table IDs over names when the table might be renamed — names work but break on rename; IDs are stable
  • Use fields aggressively — limiting the response to 3–5 fields massively reduces token usage
  • For AND/OR logic across fields, use filterByFormula — searchTerm only supports OR across fields with a single substring
  • For large tables, set a sensible maxRecords — the default paginates through the entire table which can be thousands of calls
  • Scope to a view when users have already built a saved filter in Airtable — agents don’t need to recreate the logic

​
Troubleshooting

“searchFields is required when using searchTerm”
  • Pass the list of fields to search within: searchFields: ["Name", "Description"]
  • Or use filterByFormula instead for more complex queries
“Invalid formula”
  • Wrap field names in {}: {Status}='Active', not Status='Active'
  • Escape single quotes inside string literals: \'
  • Validate the formula in Airtable’s formula field playground before passing it in
“Wrong table” / “Unknown field”
  • Call airtable_get_schema with the baseId to confirm exact table and field names
  • Field names are case-sensitive
“Results don’t match expectations with a view”
  • Views apply their own filter and sort on top of yours — if the view already hides records, your filter can only narrow further
  • Drop the view parameter to query the full table