> ## 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. # Search Airtable Tool > Query records in an Airtable table with free-text search, formula filters, or a plain list — with sort, field selection, and view scoping ## 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 | Parameter | Type | Required | Description | | ----------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `baseId` | string | Yes | Airtable base ID (starts with `app`). Get from [airtable\_get\_schema](/tools/airtable_get_schema) | | `tableIdOrName` | string | Yes | Table ID (starts with `tbl`) or the table's display name. IDs are more stable against renames | | `searchTerm` | string | No | Free-text needle. Requires `searchFields`. Matched case-insensitively as a substring | | `searchFields` | string\[] | No | Field names to search within. Required when `searchTerm` is set | | `filterByFormula` | string | No | Airtable formula to filter records. Takes precedence over `searchTerm`. Example: `"AND({Status}='Active', {Amount}>1000)"` | | `fields` | string\[] | No | Subset of field names to include in each record. If omitted, returns all fields | | `sort` | array | No | Array of `{ field, direction? }` sort rules. Applied in order (primary first) | | `maxRecords` | integer | No | Total records to return across pages (max `1000`) | | `pageSize` | integer | No | Records per page (default `100`, max `100`) | | `view` | string | No | View ID or name. When set, results honor the view's filter/sort in addition to any passed here | | `offset` | string | No | Pagination 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: "" ``` 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](/tools/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 ## Related tools * [Get Airtable Schema](/tools/airtable_get_schema) — discover `baseId`, `tableIdOrName`, and field names * [Manage Airtable Records](/tools/airtable_manage_records) — create, update, or delete records found via this tool