> ## 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](https://docs.frontic.com/api-builder/listings.md) - 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

**project-token** `string` *required*

Your project's Fetch token, embedded in the subdomain.

**slug** `string` *required*

The listing's slug, e.g. `<listing-slug>`. Per project - see your listing's detail view in the API Builder.

## Headers

See [Headers](https://docs.frontic.com/reference/fetch-api.md#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 `422 Unprocessable Entity`.

**param** `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).

**filter** `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.

**sort** `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.

**search** `string`

Free-text search query. Must be non-empty after trim. Searches across the listing's configured search fields.

**page** `integer` (default: 1)

Page number (1-based).

**limit** `integer`

Items per page. Capped by the listing's configured `perPageMax`.

## 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](https://docs.frontic.com/reference/client-sdk.md) for typed access.

### Status codes

| Code | When |
| - | - |
| `200` | Listing rendered (may have zero items) |
| `422` | 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 |
| `422` | `FETCH_API_LIMIT_EXCEEDED` - project's plan limit for Fetch API requests exceeded |

```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
  }'
```

```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 422 Unprocessable Entity theme={"theme":"css-variables"}
{
  "error": "Validation failed",
  "code": "INVALID_PARAMETERS",
  "details": [
    {
      "message": "The sorting field \"unknownField\" is not allowed.",
      "propertyPath": "sort"
    }
  ],
  "correlationId": "9f1c2e7a-4b30-4d8e-9a55-2c6f0b7d1e84"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.