Deluge Pagination: Get Every Zoho CRM Record

TL;DR: Deluge functions skip records because getRecords returns at most 200 per call and page numbers stop at 2,000 records. To process every record, loop over a fixed page list with a stop flag, use a COQL cursor on record ID for larger sets, and run a schedule function that saves a checkpoint so the next run resumes.

Key takeaways

• getRecords/searchRecords: max 200 per call.
• Page numbers stop at 2,000 records; then page_token or COQL.
• COQL ID cursor returns up to 2,000 rows per call.
• No while loop: fixed page list + stop flag.
• Run big jobs as schedule functions with a checkpoint.

A Deluge function that works perfectly in testing can quietly skip thousands of records in production. The usual cause is pagination: the function fetches the first page of 200 records, processes them and stops, or it loops through pages without noticing that page numbers stop working after 2,000 records. Deluge pagination is the set of patterns that make a function see every record it is supposed to see, within the platform's time and execution limits. This guide explains how paging works for getRecords, searchRecords and COQL from Deluge, where the limits sit, and how to checkpoint progress so long jobs can resume, with a worked example.

Why does my Deluge function skip records?

Most Deluge integration tasks return a single page. zoho.crm.v8.getRecords takes a page number and a page size, and searchRecords returns at most 200 records per call. In a sandbox with 150 test records, everything fits on one page and the function looks complete. In production, with 30,000 contacts, the same function processes the first 200 and reports success. Nothing errors; the remaining records are simply never touched.

The second trap is the page ceiling. The underlying Get Records API lets you use page numbers for up to 2,000 records. Beyond that, you must use a page_token taken from the next_page_token value in the previous response. A loop that keeps increasing the page number works until it reaches that boundary and then fails or returns nothing.

The building blocks of Deluge pagination

ToolRecords per callHow to pageBest forzoho.crm.v8.getRecordsUp to 200Page number, up to 2,000 recordsSmall modules or recent recordszoho.crm.v8.searchRecordsUp to 200Page number with criteriaRecords matching a valueGet Records via invokeapiUp to 200page_token after 2,000 recordsLarger lists in one moduleCOQL via invokeapiUp to 2,000Record ID cursor (id greater than last ID)Filtered sets of any sizeBulk Read APILarge exportsAsynchronous jobHundreds of thousands of records

Deluge has no while loop, so pagination is written as a for-each loop over a fixed list of page numbers, with a flag that stops processing once a short page arrives. The list sets a hard upper bound, which is useful: a function can never loop forever.

Related reading: Zoho CRM Bulk Write API.

How many records does zoho.crm.v8.getRecords return?

Up to 200 records per call. Page numbers work up to 2,000 records; beyond that the Get Records API needs a page_token from the previous response.

How do you page past 2,000 records in Zoho CRM?

Zoho's Functions limits and quotas set the boundaries:

• Functions triggered by workflows, Blueprints and approvals time out after 30 seconds
• Button, related list, validation rule and REST API functions time out after 10 seconds
• Schedule functions can run for up to 15 minutes
• A single invocation can execute up to 200,000 lines, counting every loop iteration and branch
• Each function execution consumes credits from a daily allowance

These numbers make it clear where large loops belong. A workflow function should never page through a whole module; it should handle the record that triggered it. Paging through thousands of records is work for a schedule function, and anything that cannot finish in 15 minutes needs a checkpoint so the next run continues where the last one stopped.

Related reading: Zoho Deluge timeout limits.

Does Deluge have a while loop?

No. Write a for-each loop over a fixed list of page numbers with a flag that stops once a short page arrives. The fixed list also means the function can never loop forever.

How do you resume a long Deluge job with a checkpoint?

Suppose a schedule function must recalculate a "Days Since Last Contact" field on every contact. The org has about 26,000 contacts. The first version below handles up to 2,000 records with page numbers. The second uses a COQL cursor and a checkpoint to handle any number. Both are illustrative and untested; adapt field names, connections and error handling to your org.

Version 1, page numbers with a stop flag:

pages = {1,2,3,4,5,6,7,8,9,10};
done = false;
processed = 0;
for each p in pages
{
    if(!done)
    {
        rows = zoho.crm.v8.getRecords("Contacts", p, 200, Map());
        for each row in rows
        {
            // recalculate and update the field here
            processed = processed + 1;
        }
        if(rows.size() < 200)
        {
            done = true;
        }
    }
}
info "Processed " + processed;

Ten pages of 200 reach exactly 2,000 records, the limit for page numbers. For 26,000 contacts, this version would stop far short, and the info line makes that visible in the logs.

Version 2, a COQL cursor with a checkpoint:

checkpoint = zoho.crm.v8.getRecordById("Sync_Checkpoints", checkpointId);
lastId = checkpoint.get("Last_Id");
batches = {1,2,3,4,5};
done = false;
for each b in batches
{
    if(!done)
    {
        q = Map();
        q.put("select_query", "select id, Last_Activity_Time from Contacts where id > " + lastId + " order by id asc limit 0, 2000");
        resp = invokeapi
        [
            service: zohocrm
            path: "/crm/v8/coql"
            type: POST
            body: q.toString()
            headers: {"content-type": "application/json"}
        ];
        rows = ifnull(resp.get("data"), List());
        for each row in rows
        {
            // recalculate and update the field here
            lastId = row.get("id");
        }
        if(rows.size() < 2000)
        {
            done = true;
            lastId = "0";   // finished: next run starts from the beginning
        }
    }
}
// save lastId back to the checkpoint record

Each run processes up to 10,000 contacts in five COQL pages and saves the last ID it reached. With 26,000 contacts, three scheduled runs cover the whole module, and if any run is cut short, the next one resumes from the saved ID rather than starting over.

RunStarting IDRecords processedSaved checkpoint1010,000ID of contact 10,0002ID of contact 10,00010,000ID of contact 20,0003ID of contact 20,000about 6,000Reset to 0

The checkpoint can live in a small custom module record, updated with zoho.crm.v8.updateRecord at the end of each run. Updating records one at a time inside the loop also consumes API calls, so for large updates collect changes and use the bulk update task instead.

Common Deluge pagination mistakes

• Processing only the first page because the sandbox never had more than 200 records
• Increasing page numbers beyond 2,000 records instead of switching to page_token or a cursor
• Using offsets on data that changes during the run, which can skip or repeat records
• Running large loops in workflow functions that time out after 30 seconds
• Forgetting that loop iterations count toward the 200,000-line limit
• Saving no checkpoint, so a failed run restarts from the beginning

Testing pagination before it reaches production

Create enough test records in a sandbox to cross each boundary: more than 200 to test page changes, and more than 2,000 if you use page numbers, so the ceiling is visible. Log the number of records processed and the last ID reached on every run, and compare the total with a record count from a report. If the numbers differ, the loop is skipping records.

When using page_token with Get Records, remember that the token is user-specific and expires at the time given in the page_token_expiry field, so a token saved for the next day's run will not work. Store record IDs as checkpoints instead; they never expire.

Paging is one part of a larger design for big jobs; our guide to the Zoho CRM schedule function covers scheduling and batch sizing for large volumes. When the work is a large update rather than a read, our guide to Zoho CRM mass update shows how decoupled batch workers keep it fast.

Frequently asked questions

How many records does zoho.crm.v8.getRecords return?

Up to 200 records per call. Page numbers work up to 2,000 records; beyond that the Get Records API needs a page_token from the previous response.

How do I get more than 2,000 records in Deluge?

Use a COQL query via invokeapi that filters on id greater than the last ID processed and orders by id, returning up to 2,000 rows per call, or the Bulk Read API for very large exports.

Does Deluge have a while loop for pagination?

No. Write a for-each loop over a fixed list of page numbers with a flag that stops once a short page arrives. The fixed list also means the function can never loop forever.

Where should large paging jobs run?

In a schedule function, which can run for up to 15 minutes per Zoho's limits, not in a workflow function, which times out after 30 seconds. Save a checkpoint so work continues on the next run.

How do we know a function processed every record?

Log a count of processed records and compare it with the module's record count, and test with more than 2,000 records before production.

Fix your Deluge functions with us

We review and rebuild Deluge functions so they page through every record, stay within limits and resume cleanly after interruptions. See our Zoho CRM automation services, or talk to us about your functions.

Related reading: Zoho CRM automation.

About the Author

Manav Sharma is the founder of Insyrge and a CRM solutions architect. He works across Zoho, Salesforce, HubSpot, Odoo and more, designing the CRM setups, integrations and automations that keep sales and operations teams working from the same data.