Pagination & Filtering

All Causeloop list endpoints (GET /v1/issues, GET /v1/patterns, etc.) use cursor-based pagination and return a consistent response envelope. This page documents the common query parameters and the page object shape.

Response envelope

Every list endpoint returns a data array and a page metadata object:

{
  "data": [ ... ],
  "page": {
    "next_cursor": "eyJvZmZzZXQiOiAyNX0",
    "has_more": true,
    "total": 142
  }
}

array

The current page of results.

string | null

An opaque cursor token. Pass it as ?cursor= on the next request to retrieve the following page. null when you are on the last page.

boolean

true if there are more results after this page.

number

Total number of matching records across all pages. May be estimated for very large result sets (>10 000 records).

Common query parameters

These parameters are supported on every list endpoint unless documented otherwise:

integer

default:"25"

Number of results per page. Minimum 1, maximum 100.

string

Opaque cursor from the previous page’s page.next_cursor. Omit for the first page.

string

Sort field with optional direction prefix. Prefix with - for descending (default on most endpoints), no prefix for ascending. Example: -created_at (newest first), created_at (oldest first).

Cursors are opaque and signed. Passing a modified or fabricated cursor string returns 400 Bad Request with code validation_error and detail "malformed cursor token".

Issues — additional filter params

string

Filter by issue status. Values: open, in_progress, resolved, closed.

string

Filter by severity. Values: critical, high, medium, low.

string

Filter issues belonging to a specific pattern.

string

Full-text search across issue title and description. Maximum 200 characters.

string

ISO-8601 UTC timestamp. Filters to issues with source_created_at on or after this instant — inclusive start of the range.

string

ISO-8601 UTC timestamp. Filters to issues with source_created_at strictly before this instant — exclusive end of the range. Together, date_from/date_to form a half-open [date_from, date_to) interval: a date_to value on a month boundary (e.g. the first of the next month) excludes that boundary instant itself.

boolean

Filter to issues that are (true) or are not (false) linked to a pattern.

date_to on this endpoint is exclusive. This differs from GET /settings/audit, whose date_to remains inclusive — a known divergence between the two endpoints, not a bug.

Patterns — additional filter params

string

Filter by pattern status. Values: active, resolved, watching.

string

Search pattern names. Maximum 200 characters.

string

Filter patterns by domain fingerprint (e.g. payments, auth).

integer

Minimum risk score (0–100, inclusive).

integer

Maximum risk score (0–100, inclusive). Must be ≥ risk_min.

Allowed sort values for patterns: risk_score, -risk_score, issue_count, -issue_count, last_seen_at, -last_seen_at.

Paginating through results

Fetch page 1, then use the returned cursor for page 2:

# Page 1
curl "https://api.causeloop.ai/v1/issues?limit=25" \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"

# Page 2 — use next_cursor from the previous response
curl "https://api.causeloop.ai/v1/issues?limit=25&cursor=eyJvZmZzZXQiOiAyNX0" \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"

async function* paginateIssues(token, params = {}) {
  const base = 'https://api.causeloop.ai/v1/issues';
  let cursor = null;

  do {
    const url = new URL(base);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    if (cursor) url.searchParams.set('cursor', cursor);

    const resp = await fetch(url, {
      headers: { 'Authorization': `Bearer ${token}` },
    });
    const body = await resp.json();

    yield* body.data;

    cursor = body.page.has_more ? body.page.next_cursor : null;
  } while (cursor);
}

// Usage — iterate all open high-severity issues
for await (const issue of paginateIssues(token, { status: 'open', severity: 'high' })) {
  console.log(issue.id, issue.title);
}

import requests

def paginate_issues(token, **params):
    url = 'https://api.causeloop.ai/v1/issues'
    cursor = None

    while True:
        query = {**params, 'limit': 25}
        if cursor:
            query['cursor'] = cursor

        resp = requests.get(
            url,
            params=query,
            headers={'Authorization': f'Bearer {token}'},
        )
        resp.raise_for_status()
        body = resp.json()

        yield from body['data']

        if not body['page']['has_more']:
            break
        cursor = body['page']['next_cursor']

# Usage
for issue in paginate_issues(access_token, status='open', severity='high'):
    print(issue['id'], issue['title'])

Filtering and sorting example

Fetch the 10 highest-risk active patterns in the payments domain:

curl "https://api.causeloop.ai/v1/patterns?status=active&domain=payments&sort=-risk_score&limit=10" \
  -H "Authorization: Bearer $CAUSELOOP_TOKEN"

const resp = await fetch(
  'https://api.causeloop.ai/v1/patterns?' +
    new URLSearchParams({ status: 'active', domain: 'payments', sort: '-risk_score', limit: '10' }),
  { headers: { 'Authorization': `Bearer ${accessToken}` } },
);
const { data } = await resp.json();

resp = requests.get(
    'https://api.causeloop.ai/v1/patterns',
    params={'status': 'active', 'domain': 'payments', 'sort': '-risk_score', 'limit': 10},
    headers={'Authorization': f'Bearer {access_token}'},
)
patterns = resp.json()['data']

​Response envelope

​Common query parameters

​Issues — additional filter params

​Patterns — additional filter params

​Paginating through results

​Filtering and sorting example

Response envelope

Common query parameters

Issues — additional filter params

Patterns — additional filter params

Paginating through results

Filtering and sorting example