Pagination

Bulk jobs can return millions of rows, so their result endpoints page the data with a cursor. This page shows how to read every row without skips or duplicates.

Use cursor pagination

Use cursor pagination when reading the results of a bulk job. It stays fast for large result sets and avoids skipped or repeated rows while a job is still being processed. Do not use offset for job results. Start with cursor=0, then pass the returned next_cursor into the next request. Stop when next_cursor is empty.

Supported result endpoints

Job type	Result endpoint
Email validity	`GET /api/jobs/validity/results`
Email identity	`GET /api/jobs/identity/results`
Email breaches	`GET /api/jobs/breaches/results`
Email gender	`GET /api/jobs/gender/results`
Email compliance	`GET /api/jobs/compliance/results`
Password breaches	`GET /api/jobs/password/results`

Every request needs the job ID as id and your API key in the Authorization header.

Query parameters

Parameter	Required	Description
`id`	Yes	The job ID returned when you created the job.
`cursor`	Yes	Use `0` for the first request; then use the preceding response’s `next_cursor`.
`page_size`	No	Number of rows to return. Use `100` by default; validity, identity, breaches, and gender support up to `200`.
`status`	No	Validity only. Filter rows by verdict, such as `valid` or `invalid`.
`breached`	No	Breaches and password jobs only. Use `1` to return only breached rows.
`found`	No	Identity and gender jobs only. Use `1` to return only found rows.

Page through results

Make the first request

Start with cursor=0.

curl "https://developer.encrata.com/api/jobs/validity/results?id=JOB_ID&cursor=0&page_size=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response returns the current items and a continuation cursor:

{
  "items": [
    {
      "email": "satya@microsoft.com",
      "status": "valid"
    }
  ],
  "next_cursor": "4213"
}

Continue until the cursor is empty

Pass next_cursor unchanged into the next request. An empty value means there are no more rows.

import requests

def iter_validity_results(job_id, api_key):
    cursor = "0"

    while True:
        response = requests.get(
            "https://developer.encrata.com/api/jobs/validity/results",
            headers={"Authorization": f"Bearer {api_key}"},
            params={"id": job_id, "cursor": cursor, "page_size": 100},
        )
        response.raise_for_status()
        page = response.json()

        yield from page["items"]

        cursor = page["next_cursor"]
        if not cursor:
            return

async function* validityResults(jobId, apiKey) {
  let cursor = "0";

  while (true) {
    const params = new URLSearchParams({ id: jobId, cursor, page_size: "100" });
    const response = await fetch(
      `https://developer.encrata.com/api/jobs/validity/results?${params}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );

    if (!response.ok) throw new Error(`Request failed (${response.status})`);
    const page = await response.json();

    yield* page.items;

    cursor = page.next_cursor;
    if (!cursor) return;
  }
}

Do not calculate the next page from a row count or send offset. Only next_cursor determines whether another page is available.

Overview

Configuration

Best practices

Supported result endpoints

Query parameters

Page through results

Next steps

Bulk operations

Rate limits

​Use cursor pagination

​Supported result endpoints

​Query parameters

​Page through results

​Next steps

Bulk operations

Rate limits

Use cursor pagination

Supported result endpoints

Query parameters

Page through results

Next steps