# Search and filtering (/docs/guides/search-and-filtering)

Most AISquare list endpoints accept the same query parameters for search,
filtering, sorting, and pagination. Learn them once and they apply across the
API. These features are what make discovery pages, search experiences, and
scalable feeds possible.

The examples below use the flattened experiences endpoint, but the parameters
work the same way on other list endpoints.

## Search [#search]

Search retrieves content by free text, typically across titles, tags,
categories, and focus areas.

```text
GET /aistudios/experiences/flattened/?search=machine%20learning
```

Keep queries short, and combine search with filters for sharper results.

## Filtering [#filtering]

Filters narrow results by a specific field.

| Parameter         | Description                 |
| ----------------- | --------------------------- |
| `type`            | Filter by resource type     |
| `category`        | Filter by category ID       |
| `category_name`   | Filter by category name     |
| `tags`            | Filter by tags              |
| `publication_url` | Filter by a specific studio |

Combine filters by adding more parameters:

```text
GET /aistudios/experiences/flattened/?type=AI_EXPERT&category_name=ai
```

## Sorting [#sorting]

Use `ordering` to control the order of results.

| Value      | Description                     |
| ---------- | ------------------------------- |
| `trending` | Based on engagement and recency |
| `newest`   | Most recently created           |
| `popular`  | Highest engagement              |
| `updated`  | Recently updated                |

```text
GET /aistudios/experiences/flattened/?ordering=trending
```

Prefix the value with `-` for descending order:

```text
GET /aistudios/experiences/flattened/?ordering=-newest
```

## Pagination [#pagination]

Pagination returns large datasets in smaller pages.

| Parameter   | Description      |
| ----------- | ---------------- |
| `page`      | Page number      |
| `page_size` | Results per page |

```text
GET /aistudios/experiences/flattened/?page=1&page_size=10
```

The response wraps the results with paging metadata:

```json title="Paged response"
{
  "count": 100,
  "next": "url_to_next_page",
  "previous": null,
  "results": []
}
```

Follow `next` to load more, and stop when it is `null`.

## Combining everything [#combining-everything]

Search, filters, sorting, and pagination compose into one request.

```text
GET /aistudios/experiences/flattened/?search=ai&type=AI_EXPERT&ordering=trending&page=1&page_size=10
```

## Performance best practices [#performance-best-practices]

* **Always paginate.** Never fetch a full dataset in one request.
* **Keep pages small.** Ten to twenty items per page is a reasonable default.
* **Filter early.** Narrow on the server to cut payload size.
* **Cache hot queries.** Trending and popular results are good candidates.

## Common mistakes [#common-mistakes]

* **Fetching everything at once.** Slow responses and large payloads.
* **Ignoring `next`.** Skipping pagination leaves data behind.
* **Overusing search.** Prefer filters where a field match will do.

## Example flow [#example-flow]

1. The user searches for "ai".
2. Apply a filter, for example `type=AI_EXPERT`.
3. Sort by `trending`.
4. Fetch page 1.
5. Load more by following `next`.

## Next steps [#next-steps]

<Cards>
  <Card title="Quickstart" href="/docs/getting-started/quickstart" description="Make your first filtered request." />

  <Card title="Core Concepts" href="/docs/getting-started/core-concepts" description="Resource types and the entities you filter on." />

  <Card title="Content modeling" href="/docs/guides/content-modeling" description="Structure and display the resources you fetch." />

  <Card title="Errors" href="/docs/reference/errors" description="Handle query and pagination errors." />
</Cards>