---
title: V8 API Results Endpoint
description: "# V8 API Results Endpoint (`/api/results`) The Results endpoint allows you to retrieve data produced by RTILA project executions. It supports a powerful filter language, pagination, and sorting so you can select exactly the records you need. To see how…"
url: "https://legacy.rtila.com/docs/v8-api-results-endpoint/"
updated: "2025-11-30"
category: "API & Cloud"
---

# V8 API Results Endpoint

# V8 API Results Endpoint (`/api/results`)

The Results endpoint allows you to retrieve data produced by RTILA project executions. It supports a powerful filter language, pagination, and sorting so you can select exactly the records you need.

To see how this endpoint fits into the full workflow, start with [V8 API Overview](/docs/v8-api-overview/), and for triggering new runs see [V8 API Remote Execution](/docs/v8-api-remote-execution/).

## Endpoint Summary

| Method | `GET` |
| --- | --- |
| Path | `/api/results` |
| Base URL (Local) | `http://127.0.0.1:8880` |
| Base URL (Remote/Public) | `https://YOUR_PUBLIC_RTILA_HOST` |

## Request

### Headers

| Header | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | `Bearer YOUR_SYSTEM_AUTH_TOKEN` (JWT from RTILA Studio). |

### Query Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `filter` | `string` | Yes | SQL-like filter expression to select records (e.g. by `sessionId`, `dataset`, or custom fields). |
| `page` | `number` | No | Page number for pagination. Default is `1`. |
| `perPage` | `number` | No | Items per page. Default is `30`. |
| `sort` | `string` | No | Field to sort by. Prefix with `-` for descending (e.g. `-created`, `-Price`). |

## Filtering (`filter`)

The `filter` parameter uses a parenthesized, SQL-like syntax:

```
filter=(<field><operator>'<value>')
```

### Equality

```
filter=(sessionId='ilh2f81bq46wedu')
```

Most commonly used to restrict results to a single execution run (session).

### AND (`&&`)

```
filter=(sessionId='ilh2f81bq46wedu' && dataset='BookData')
```

### OR (`||`)

```
filter=(price='£53.74' || price='£51.77')
```

### Common Fields

- `sessionId` – essential when working with remote runs; use the `queueId` from `POST /api/remote`.
- `dataset` – restricts results to a specific dataset (e.g. `BookData`).
- Custom data fields – you can filter on any field stored in your dataset (e.g. `Title`, `Price`, `Image_url`, `Status`).

### Example: Filter by Session and Title

```bash
curl -X GET "http://127.0.0.1:8880/api/results?filter=(sessionId='ilh2f81bq46wedu' && Title='A Light in the Attic')" 
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN"
```

## Pagination (`page` & `perPage`)

Use pagination to retrieve large result sets in manageable chunks.

- `perPage` – items per page (default `30`).
- `page` – page number to retrieve (default `1`).

### Example: Page 3, 50 Items per Page

```bash
curl -X GET "http://127.0.0.1:8880/api/results?filter=(sessionId='ilh2f81bq46wedu')&perPage=50&page=3" 
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN"
```

## Sorting (`sort`)

Sort the results by a field in ascending or descending order.

### Ascending

```
sort=Price
sort=Title
```

### Descending

```
sort=-created
sort=-Price
```

A common pattern is `sort=-created` to get the newest records first.

### Example: Newest Records First

```bash
curl -X GET "http://127.0.0.1:8880/api/results?filter=(sessionId='ilh2f81bq46wedu')&sort=-created" 
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN"
```

## Combining Filter, Pagination & Sorting

You can combine all options in a single request.

**Goal:**

- Within a specific `sessionId`
- Limit to dataset `BookData`
- Filter to items with price > £50
- Sort from highest to lowest price
- Return only the first 10 items

**Note:** The comparison operator (`>`) here is illustrative. Depending on how your data is stored (strings vs numbers), you may need to normalize values or adjust the operator.

```bash
curl -X GET "https://YOUR_PUBLIC_RTILA_HOST/api/results?filter=(sessionId='ilh2f81bq46wedu' && dataset='BookData' && Price > '50.00')&sort=-Price&perPage=10&page=1" 
  -H "Authorization: Bearer YOUR_SYSTEM_AUTH_TOKEN"
```

## Response Structure

```json
{
  "items": [
    {
      "Title": "Tipping the Velvet",
      "Price": "£53.74",
      "Image_url": "https://books.toscrape.com/media/cache/26/0c/260c6ae16bce31c8f8c95daddd9f4a1c.jpg",
      "id": "record-id",
      "collectionId": "collection-id"
      /* additional metadata fields may be present */
    }
  ],
  "page": 1,
  "perPage": 30,
  "totalItems": 1,
  "totalPages": 1
}
```

| Field | Type | Description |
| --- | --- | --- |
| `items` | `array` | Array of result records (one object per row in your dataset). |
| `page` | `number` | Current page number. |
| `perPage` | `number` | Number of items returned per page. |
| `totalItems` | `number` | Total number of items that match the filter. |
| `totalPages` | `number` | Total pages available given `perPage` and the filter. |

Each object in `items` contains:

- Your dataset fields (e.g. `Title`, `Price`, `Image_url`).
- System metadata fields (e.g. `id`, `collectionId`, timestamps).

To create new runs and get fresh data into this endpoint, use [V8 API Remote Execution (`/api/remote`)](/docs/v8-api-remote-execution/).