> ## Documentation Index
> Fetch the complete documentation index at: https://docs.frontic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch a Listing

Fetch a [Search Listing](/api-builder/listings) — a searchable, filterable, sortable, paginated collection. The body controls every aspect of the query: parameters that scope the listing (e.g. a category ID), free-text `search`, structured `filter` expressions, `sort`, and pagination via `page` + `limit`.

## Path Parameters

<ParamField path="project-token" type="string" required>
  Your project's Fetch token, embedded in the subdomain.
</ParamField>

<ParamField path="slug" type="string" required>
  The listing's slug, e.g. `<listing-slug>`. Per project — see your listing's detail view in the API Builder.
</ParamField>

## Headers

See [Headers](/reference/fetch-api#headers) on the overview for the full set. Listings honour `fs-context`, `fs-domain`, `fs-version`, and `fs-secret` (only when the project has fetch keys configured).

## Request Body

All body fields are optional unless the listing's parameter definition declares one as required. Only six top-level keys are accepted; any other key returns `400 Bad Request`.

<ParamField body="param" type="object">
  Listing parameters. Shape is defined per listing in the API Builder. Required keys must be present; values are typed (string or array of strings).
</ParamField>

<ParamField body="filter" type="array">
  Structured filter expressions. Each entry is one of three shapes:

  ```json equals / contains theme={"theme":"css-variables"}
  { "type": "equals", "field": "<filter-field>", "value": "<value>" }
  ```

  ```json range theme={"theme":"css-variables"}
  { "type": "range", "field": "<numeric-field>", "from": <number>, "to": <number> }
  ```

  ```json or / not (nested) theme={"theme":"css-variables"}
  { "type": "or", "filter": [/* nested filter array */] }
  ```

  For `range`, supply `from`, `to`, or both. Filter `field` values must be among the listing's configured filter fields.
</ParamField>

<ParamField body="sort" type="string | object | array">
  Sort instructions. Accepts three shapes:

  ```json field name (defaults to asc) theme={"theme":"css-variables"}
  "<sort-field>"
  ```

  ```json sort object theme={"theme":"css-variables"}
  { "field": "<sort-field>", "order": "asc" }
  ```

  ```json array of sort objects (applied left-to-right) theme={"theme":"css-variables"}
  [
    { "field": "publishedAt", "order": "desc" },
    { "field": "name", "order": "asc" }
  ]
  ```

  `order` is `"asc"` or `"desc"`. `field` values must be among the listing's configured sort fields.
</ParamField>

<ParamField body="search" type="string">
  Free-text search query. Must be non-empty after trim. Searches across the listing's configured search fields.
</ParamField>

<ParamField body="page" type="integer" default="1">
  Page number (1-based).
</ParamField>

<ParamField body="limit" type="integer">
  Items per page. Capped by the listing's configured `perPageMax`.
</ParamField>

## Response

Returns the listing's records as defined by the per-item block, plus pagination metadata. Exact shape depends on the listing definition — generate the [Client SDK](/reference/client-sdk) for typed access.

### Status codes

| Code  | When                                                                                                                                                                                |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Listing rendered (may have zero items)                                                                                                                                              |
| `400` | Body validation failed — unknown filter field, sort field not in allowed sorts, `limit` above the configured max, search empty, etc. The `details` array spells out each violation. |
| `401` | `fs-secret` missing or wrong (only when the project has fetch keys configured)                                                                                                      |
| `404` | Listing slug doesn't exist for the resolved context                                                                                                                                 |
| `403` | Project's plan limit for Fetch API requests exceeded                                                                                                                                |

<RequestExample>
  ```bash curl theme={"theme":"css-variables"}
  curl -X POST 'https://fetch-<project-token>.frontic.com/listing/<listing-slug>' \
    -H 'fs-context: <context-key>' \
    -H 'Content-Type: application/json' \
    -d '{
      "param": { "categoryId": "shoes" },
      "filter": [
        { "type": "equals", "field": "color", "value": "Red" },
        { "type": "range", "field": "price", "from": 5000, "to": 25000 }
      ],
      "sort": [{ "field": "publishedAt", "order": "desc" }],
      "search": "running",
      "page": 1,
      "limit": 24
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"theme":"css-variables"}
  {
    "items": [
      {
        "name": "Aurora Trail Runner",
        "price": { "amount": 12900, "currency": "eur", "precision": 2 }
      }
    ],
    "_meta": {
      "total": 138,
      "page": 1,
      "limit": 24,
      "facets": {
        "color": [
          { "value": "Red", "count": 12 },
          { "value": "Black", "count": 28 }
        ]
      }
    }
  }
  ```

  ```json 400 Bad Request theme={"theme":"css-variables"}
  {
    "error": "Validation failed",
    "code": "INVALID_PARAMETERS",
    "details": [
      {
        "message": "The sorting field \"unknownField\" is not allowed.",
        "propertyPath": "sort"
      }
    ]
  }
  ```
</ResponseExample>