Pagination & Filtering

All TruthVouch list endpoints support pagination, sorting, and filtering to help you work with large datasets efficiently.

Pagination

All list endpoints return paginated results:

curl "https://api.truthvouch.com/api/v1/alerts" \
  -H "Authorization: Bearer tv_live_..."

Response:

{
  "data": [
    {"id": "alert-1", "severity": "high"},
    {"id": "alert-2", "severity": "medium"}
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 1250,
    "totalPages": 50
  }
}

Query Parameters

Parameter	Default	Max	Description
`page`	1	N/A	Page number (1-indexed)
`pageSize`	25	100	Results per page
`sortBy`	createdAt	N/A	Field to sort by
`sortOrder`	desc	N/A	asc or desc

Examples

Get page 2 with 50 results:

curl "https://api.truthvouch.com/api/v1/alerts?page=2&pageSize=50"

Sort by severity (ascending):

curl "https://api.truthvouch.com/api/v1/alerts?sortBy=severity&sortOrder=asc"

Get last page:

# Use meta.totalPages from response
page = total / pageSize + (1 if total % pageSize else 0)
curl "https://api.truthvouch.com/api/v1/alerts?page={page}"

Metadata

Response meta tells you about your result set:

{
  "meta": {
    "page": 2,
    "pageSize": 50,
    "total": 1250,
    "totalPages": 25
  }
}

Fields:

page — Current page number
pageSize — Results returned per page
total — Total results across all pages
totalPages — Total number of pages

Filtering

Filter results by field values:

curl "https://api.truthvouch.com/api/v1/alerts?severity=high&status=open" \
  -H "Authorization: Bearer tv_live_..."

Response (only alerts with severity=high AND status=open):

{
  "data": [
    {"id": "alert-1", "severity": "high", "status": "open"},
    {"id": "alert-3", "severity": "high", "status": "open"}
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 47,
    "totalPages": 2
  }
}

Available Filters by Endpoint

Filters vary by endpoint. Check endpoint docs for supported filters.

Common filters:

status — open, resolved, ignored
severity — critical, high, medium, low
type — hallucination, pii_detected, injection_attempt
createdAfter — ISO 8601 timestamp
createdBefore — ISO 8601 timestamp
clientId — Organization ID (multi-tenant)

Filter Operators

Most filters support standard operators:

Operator	Syntax	Example
Equals	`field=value`	`severity=high`
Not Equals	`field!=value`	`status!=resolved`
Greater Than	`field>value`	`score>0.8`
Less Than	`field<value`	`score<0.5`
In List	`field=[v1,v2,v3]`	`status=[open,pending]`
Date Range	`field>=date&field<=date`	`createdAfter=2024-01-01&createdBefore=2024-12-31`

Date Filtering

Filter by date range using ISO 8601 format:

# Alerts created in March 2024
curl "https://api.truthvouch.com/api/v1/alerts?\
createdAfter=2024-03-01T00:00:00Z&\
createdBefore=2024-03-31T23:59:59Z"

Sorting

Control result order with sortBy and sortOrder:

# Sort by severity ascending
curl "https://api.truthvouch.com/api/v1/alerts?sortBy=severity&sortOrder=asc"

# Sort by creation date descending (newest first)
curl "https://api.truthvouch.com/api/v1/alerts?sortBy=createdAt&sortOrder=desc"

Default Sort

If not specified:

sortBy: createdAt (most recent first)
sortOrder: desc (newest first)

Sortable Fields

Vary by endpoint, but typically include:

id — Resource ID
createdAt — Creation timestamp
updatedAt — Last update timestamp
name — Resource name
status — Current status
severity — Alert severity

Combined Queries

Combine pagination, filtering, and sorting:

# High-severity alerts from March 2024, page 2, sorted by date
curl "https://api.truthvouch.com/api/v1/alerts?\
severity=high&\
createdAfter=2024-03-01&\
createdBefore=2024-03-31&\
page=2&\
pageSize=50&\
sortBy=createdAt&\
sortOrder=desc"

Efficient Pagination

Using Offset/Limit

For large datasets, use cursor-based pagination (when available):

# Get first 100 results
curl "https://api.truthvouch.com/api/v1/alerts?pageSize=100"

# Get next 100 using cursor
curl "https://api.truthvouch.com/api/v1/alerts?cursor=abc123&pageSize=100"

Cursor pagination is more efficient than offset for large result sets.

Handling Large Result Sets

For millions of results, use streaming APIs or batch exports instead of paginating:

# Instead of paginating 1 million alerts...
# Use batch export
POST /api/v1/batch/export \
  filter={"severity": "high"}

Avoid N+1 Queries

When processing paginated results, consider:

# Load all data in fewer API calls
alerts = []
page = 1
while page:
    response = requests.get(
        "https://api.truthvouch.com/api/v1/alerts",
        params={"page": page, "pageSize": 100}
    )
    alerts.extend(response.json()["data"])

    # Check if more pages exist
    meta = response.json()["meta"]
    if page >= meta["totalPages"]:
        break
    page += 1

Caching

Cache paginated results when appropriate:

import hashlib
import json

def get_alerts_cached(severity, page):
    cache_key = hashlib.md5(
        f"{severity}:{page}".encode()
    ).hexdigest()

    # Check cache
    cached = redis_client.get(cache_key)
    if cached:
        return json.loads(cached)

    # Fetch from API
    response = requests.get(
        "https://api.truthvouch.com/api/v1/alerts",
        params={"severity": severity, "page": page}
    )
    result = response.json()

    # Cache for 5 minutes
    redis_client.setex(cache_key, 300, json.dumps(result))

    return result

Python SDK Examples

Python

from truthvouch import TruthVouchClient

async with TruthVouchClient(api_key="tv_live_...") as client:
    # Get page 1
    response = await client.api.get_alerts(
        page=1,
        pageSize=50,
        severity="high",
        sortBy="createdAt",
        sortOrder="desc"
    )

    print(f"Total alerts: {response.meta.total}")
    print(f"Pages: {response.meta.totalPages}")
    for alert in response.data:
        print(f"  - {alert.id}: {alert.message}")

    # Get next page
    if response.meta.page < response.meta.totalPages:
        next_page = await client.api.get_alerts(
            page=response.meta.page + 1,
            pageSize=50
        )

TypeScript

const tv = new TruthVouch({ apiKey: 'tv_live_...' });

const response = await tv.api.alerts.list({
  page: 1,
  pageSize: 50,
  severity: 'high',
  sortBy: 'createdAt',
  sortOrder: 'desc',
});

console.log(`Total: ${response.meta.total}`);
console.log(`Pages: ${response.meta.totalPages}`);

response.data.forEach(alert => {
  console.log(`  - ${alert.id}: ${alert.message}`);
});

Search vs Filter

Filter — Exact match on field values (fast, indexed)
Search — Full-text search across multiple fields (slower)

Use filters for structured queries, search for content lookup.