> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Using paramsIO
> Filter, paginate, and sort Automation API query results using the paramsIO object, with examples for retrieving sites, experiments, and combined filters.
## Goal
The Automation API uses a `paramsIO` object to filter, paginate, and sort query collections. This tutorial demonstrates practical use cases for `paramsIO`, including:
* **Retrieving multiple `siteId`s** using `siteCode` values
* **Filtering experiments** by status
* **Setting pagination criteria** to control result size
The `paramsIO` pattern is used across many endpoints and follows a consistent structure, making it a powerful tool for precise data retrieval.
## Requirements
### Access token
The Automation API requires an **access token**.
Retrieve the token programmatically by following the instructions in the [Get started article](/developer-docs/apis/automation-api-rest/get-started/get-started#obtaining-an-access_token).
***
## Understanding paramsIO
The `paramsIO` object passes structured queries to API endpoints. It typically includes pagination, sorting, and filtering tools. Refer to the [Get started article](/developer-docs/apis/automation-api-rest/get-started/get-started#api-usage--paginate-filter-and-sort-parameters) for more information on `paramsIO`.
### Filter Structure
Filters use a consistent JSON structure:
| Property | Type | Description |
| :----------- | :----- | :------------------------------------------------------------------------------ |
| `field` | String | The property in the collection to filter by (for example, `"code"`, `"status"`) |
| `operator` | String | The comparison operator (for example, `"EQUAL"`, `"BETWEEN"`, `"GREATER"`) |
| `parameters` | Array | An array of values to match against |
Filter JSON objects must be **URL-encoded** when added to the endpoint URL. For example, `[` becomes `%5B` and `"` becomes `%22`.
***
## Use case 1: Retrieve multiple siteIds by siteCode
The Automation API requires the internal numeric `id` for most operations. This example retrieves multiple site IDs simultaneously using `siteCode` values.
### Step 1: Define the filter
To retrieve multiple sites, use the `EQUAL` operator with an array of site codes:
```json theme={null}
[
{
"field": "code",
"operator": "EQUAL",
"parameters": ["xdrio4plsn", "adflwp2mms", "lricdj5pqw"]
}
]
```
### Step 2: Send the request
Send a `GET` request to the `/sites` endpoint with the URL-encoded filter:
**Endpoint:** `GET https://api.kameleoon.com/sites`
**Example request:**
```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/sites?filter=%5B%7B%22field%22%3A%22code%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%2C%22adflwp2mms%22%2C%22lricdj5pqw%22%5D%7D%5D' \
-H 'Authorization: Bearer '
```
### Step 3: Handle the response
The API returns all matching sites in a JSON array:
```json theme={null}
[
{
"id": 42099,
"url": "https://www.example-production.com/",
"name": "Production Environment",
"code": "xdrio4plsn"
...
},
{
"id": 42100,
"url": "https://www.example-staging.com/",
"name": "Staging Environment",
"code": "adflwp2mms"
...
},
{
"id": 42101,
"url": "https://www.example-test.com/",
"name": "Test Environment",
"code": "lricdj5pqw"
...
}
]
```
Use these `id` values for subsequent API operations.
***
## Use case 2: Filter active experiments with pagination
This example demonstrates how to combine filtering and pagination to retrieve active experiments in manageable batches.
### Step 1: Define the filter and pagination
Create a filter for active experiments and specify pagination parameters:
**Filter JSON:**
```json theme={null}
[
{
"field": "status",
"operator": "EQUAL",
"parameters": ["ACTIVE"]
}
]
```
**Pagination parameters:**
* `page=1`: First page of results
* `perPage=200`: Limit to 200 items per page
### Step 2: Send the request
Send a `GET` request to the `/experiments` endpoint:
**Endpoint:** `GET https://api.kameleoon.com/experiments`
**Example request:**
```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/experiments?perPage=200&page=1&filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%5D' \
-H 'Authorization: Bearer '
```
### Step 3: Handle the response
The API returns up to 200 active experiments:
```json theme={null}
[
{
"id": 12345,
"siteId": 54321,
"name": "My Active Experiment",
"description": "Testing new checkout page",
"baseURL": "https://yourwebsite.com",
"type": "AI",
"trackingTools": [],
"status": "ACTIVE",
"dateCreated": "2026-02-03T18:41:00",
"tags": ["checkout", "mobile"],
...
}
]
```
**To retrieve additional pages**, increment the `page` parameter in subsequent requests.
***
## Use case 3: Combining multiple filters
To query more precisely, combine multiple filter conditions. For example, find active experiments on a specific site:
```json theme={null}
[
{
"field": "status",
"operator": "EQUAL",
"parameters": ["ACTIVE"]
},
{
"field": "siteId",
"operator": "EQUAL",
"parameters": ["xdrio4plsn"]
}
]
```
**Example request:**
```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/experiments?filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%2C%7B%22field%22%3A%22siteId%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%5D%7D%5D' \
-H 'Authorization: Bearer '
```
***
## Best Practices
1. **URL Encoding**: URL-encode the filter JSON before adding it to the request URL.
2. **Pagination**: Use `perPage` to limit result size and prevent timeouts on large collections
3. **Multiple filters**: Combine filter conditions to reduce unnecessary data transfer
4. **Operator choice**: Use operators for multiple values instead of multiple separate requests
## Related Resources
* [Automation API Get Started](/developer-docs/apis/automation-api-rest/get-started/get-started)
* [Find the siteCode](/user-manual/faq#how-do-i-find-my-sitecode)