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

# Filtering

> Learn how to filter API results to retrieve specific subsets of data

## Overview

The Cevoid API supports filtering to help you retrieve specific subsets of data from your requests. Filters allow you to narrow down results based on criteria such as label associations, making it easier to work with targeted datasets.

## Filter Structure

Filters are passed as a URL-encoded JSON string containing an array of filter objects. Each filter object must include three required fields:

* **`type`**: The type of filter to apply
* **`operator`**: How to combine multiple values
* **`values`**: Array of IDs to filter by

### Supported Filter Types

* **`label`**: Filter posts by their associated labels

### Supported Operators

* **`OR`**: Returns posts matching **any** of the provided values
* **`AND`**: Returns posts matching **all** of the provided values

***

## Basic Filtering

### Filter by Single Label

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011"]}]'
```

### Filter by Multiple Labels (OR)

Returns posts that have **at least one** of the specified labels:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"OR","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'
```

### Filter by Multiple Labels (AND)

Returns posts that have **all** of the specified labels:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -G https://api.cevoid.com/v1/posts \
  -H "x-api-key: {your-api-key}" \
  --data-urlencode 'filter=[{"type":"label","operator":"AND","values":["507f1f77bcf86cd799439011","507f191e810c19729de860ea"]}]'
```

***

## Common Errors

### Invalid JSON Format

```
Unexpected token in JSON at position 0
```

**Solution**: Ensure your filter is valid JSON and properly URL-encoded.

### Invalid ID Format

```
Filter value "invalid-id" is not a valid ID
```

**Solution**: All values in the filter must be valid IDs (24-character hexadecimal strings). You can obtain label IDs from your dashboard under Settings → Labels.

### Unsupported Filter Type

```
Filter type category is not supported
```

**Solution**: Currently only `label` is supported as a filter type.

### Unsupported Operator

```
Filter operator > is not supported
```

**Solution**: Only `OR` and `AND` operators are supported.

### Missing Required Fields

```
Type is required
```

```
Operator is required
```

```
Values is required
```

**Solution**: Each filter object must include `type`, `operator`, and `values` fields.

### Invalid Array Structure

```
Filter param needs to be an array
```

**Solution**: The filter parameter must be a JSON array, even if you're only filtering by one label.

```
Filter values must be an array
```

**Solution**: The `values` field must be an array of IDs.

***

## Filter Best Practices

### Getting Label IDs

To use label filters, you'll need the unique ID for each label:

1. Log in to your Cevoid account
2. Navigate to **Settings** → **Labels**
3. Find the label you want to filter by
4. Copy the label ID (shown as a 24-character string)

<Note>
  You can find your labels at: [https://app.cevoid.com/settings/labels <Icon icon="square-arrow-out-up-right" />](https://app.cevoid.com/settings/labels)
</Note>

### Important Considerations

<Warning>
  Always URL-encode your filter parameter when making requests. Invalid JSON format or incorrectly formatted IDs will result in 400 errors.
</Warning>