***

title: 'Search, filtering, and pagination'
description: Retrieve and refine data efficiently using AISquare APIs.
----------------------------------------------------------------------

This guide explains how to retrieve and refine data efficiently using AISquare APIs.

These features are essential for building:

* Discovery pages
* Search experiences
* Scalable feeds

***

## Overview

Most AISquare endpoints support:

* **Search**
* **Filtering**
* **Sorting**
* **Pagination**

These are applied using query parameters.

***

## Search

Search allows you to retrieve content using free text.

### Example

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

### What search covers

Search typically works across:

* Titles
* Tags
* Categories
* Focus areas

### Best practices

* Keep search queries simple
* Avoid overly long strings
* Combine with filters for better results

***

## Filtering

Filtering allows you to narrow down results based on specific fields.

### Common filters

| 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 specific studio |

### Example

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

### Multiple filters

You can combine filters:

```
GET /api/v1/aistudios/experiences/flattened/?type=AI_NOTE&search=data
```

***

## Sorting

Sorting controls the order of results.

### Supported options

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

### Example

```
GET /api/v1/aistudios/experiences/flattened/?ordering=trending
```

### Ascending vs descending

Use `-` prefix for descending order:

```
GET /api/v1/aistudios/experiences/flattened/?ordering=-newest
```

***

## Pagination

Pagination allows you to retrieve large datasets in smaller chunks.

### Parameters

| Parameter   | Description                |
| ----------- | -------------------------- |
| `page`      | Page number                |
| `page_size` | Number of results per page |

### Example

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

### Response structure

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

### How to use pagination

* Use `next` to load more results
* Stop when `next` is `null`

***

## Combining everything

You can use search, filters, sorting, and pagination together.

### Example

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

***

## Performance best practices

### Use pagination always

Avoid fetching large datasets in a single request.

### Limit page size

Use reasonable values like:

* 10–20 items per page

### Combine filters early

Reduce unnecessary data transfer.

### Cache frequent queries

Especially for:

* Trending content
* Popular resources

***

## Common mistakes

### Fetching all data at once

Leads to slow performance and large payloads.

### Not handling pagination

Missing `next` leads to incomplete data.

### Overusing search

Use filters when possible for better performance.

***

## Example implementation flow

1. User searches for "ai"
2. Apply filters (`type = AI_EXPERT`)
3. Sort by trending
4. Fetch page 1
5. Load more using `next`

***

## Related pages

* [Core Concepts](/docs/getting-started/core-concepts) — understand resource types and entities
* [AI Studios](/docs/product/ai-studios) — the flattened experiences endpoint
* [Content modeling guide](/docs/data-ux-guides/content-modeling-guide) — structure and display resources
* [Community](/docs/product/community) — explore public experiences with filtering
* [Quickstart](/docs/getting-started/quickstart) — make your first filtered request
* [Errors](/docs/reference/errors) — handle pagination and query errors