Lists

Rows of products for your pages, such as Popular or New arrivals, and menus of a field's values with their counts. Built ahead and served from a cache, so they aren't searches.

A list is a named row your pages show: Popular, New arrivals, On sale, a holiday's products, or a menu of themes or categories with how many products each has. You set it up once, and your pages ask for it by its ID:

const [popular, themes] = await client.lists(["popular", "themes"])

Each list is a filter and a sort, with products pinned first or hidden. Findlane builds it ahead of time and keeps it in a cache near your shoppers, so a page gets its lists in a few milliseconds. List requests aren't searches: they never count toward your plan's searches.

You can rename, reorder or change a list without touching your site's code.

Set one up

In the dashboard, open an index and choose Lists, then New list. Give it an ID (such as popular or new-arrivals), a title your pages can show, and choose what it holds:

• Products: a row of products from filters and one of the index's sorts, such as popularity or newest first. Without a sort, it uses the index's default.
• Values of a field: a facet field's values with how many products each has, the most first or by name. Use it for a menu of themes, brands or categories.

The editor shows what the list holds as you change it. Hover a product or value to pin it first or hide it from the list, or search the index to pin a product that isn't in the row.

Agents can set lists up too, with the save_list tool. Servers can use the API or the server SDK.

Settings

Sold-out products follow the index's rank first setting, as in a search. To leave them out, add a filter.

On your pages

Ask for all of a page's lists in one request. It's a GET, so browsers send it without asking the API first, and they may keep the answer for 30 seconds.

With the browser SDK (0.15.0):

// One list; a FindlaneError with status 404 when the index has no such list
const popular = await client.list("popular")

// Several, in the order asked; IDs the index has no list for are left out
const lists = await client.lists(["halloween", "new-arrivals", "themes"])

Without the SDK:

const response = await fetch(
  `https://api.findlane.dev/api/public/indexes/${publicId}/lists?ids=halloween,themes`
)
const { lists } = await response.json()

On a server-rendered page, read them with an API key that has the search scope: index.lists.getMany(["popular", "themes"]) with the server SDK (0.17.0).

What a list holds

{
  "id": "halloween",
  "title": "Halloween is coming",
  "kind": "products",
  "hits": [{ "id": "h4", "record": { "title": "Latex mask", "price": 1990 } }],
  "browse": { "sort": "popular", "filters": { "category": "halloween" } },
  "updatedAt": "2026-10-14T09:12:03.000Z"
}

hits are products as a search response's hits are, without highlights. A list of values has kind: "values", field, and values: [{ "value": "Bluey", "count": 41 }] instead. browse is the list's filters and sort, for a "See all" link that opens the same products as a search. updatedAt is when what the index's lists hold last changed.

?limit= gives fewer products or values than the list holds, such as 4 on a phone.

How fresh lists are

• Saving a list builds it before the dashboard (or the API) answers.
• A change to the index reaches its lists within about a minute. The edge sees a rebuilt list within seconds.
• Refresh now on the Lists page builds them again at once. It's allowed once a minute per index.
• A list that stops working, such as one filtering on a field that was removed from the settings, keeps what it held before. The Lists page says why.

Browser search access

Browsers get lists from the same allowed origins as browser search. With a public search policy, products have only the fields the policy returns, and a list of values is left out unless the policy lets browsers facet on its field. API keys and the dashboard get every field.

Limits