Articles in this section

Configure advanced API settings

Advanced API settings control how long an API waits for a request to finish, whether it returns results in pages, what it does when a connection is offline, and whether it checks requests and responses against your schemas. The settings apply only to the API you're editing. You need the Manage permission on the integration or the Administrator role on the account.

API settings

  1. Go to Build build-icon.png, and then select APIs. Select API builder, and then select your API.
  2. Select Settings.
  3. Change the settings you need.
  4. Select Save.

The General section holds these settings.

Setting Description
Name The API's name.
Description An optional description.
Version The API's version, which is part of its URI.
Invoke URL The URL callers use. Read only. Select the copy icon to copy it.
Download OpenAPI spec Downloads the OpenAPI specification for the API.

The Advanced section holds the settings in this table.

Setting Description
Override timeout The number of seconds, from 0 to 120, this API waits for a request to finish. Takes precedence over your account's organization-wide timeout. See Set the API timeout.
Enable pagination Returns large result sets in pages. See Paginate API responses.
Immediate error for offline connections Returns HTTP 500 right away when a connection the API uses is offline. See Handle offline connections.
Enable request/response validation Checks every request and response against the schemas defined for this API. See Turn on validation.

Set the API timeout

An API times out after your account's organization-wide API timeout, which is 120 seconds unless an account owner or administrator changes it. To change the organization-wide timeout, go to Account avatar-icon.png, and then select Company, and then select API builder. To use a different timeout for one API, enter a value from 0 to 120 in Override timeout. The override can be longer or shorter than the organization-wide timeout.

Paginate API responses

Select Enable pagination when an API is likely to return large result sets. Callers then page through the full result set using the token returned with each response. The API's OpenAPI specification is updated to document pagination in the request and response schemas.

Pagination is available when the API's first lookup, which is the lookup that runs earliest, uses HTTP, Salesforce, or NetSuite as its source. If the first lookup uses a relational database or another source type, you can't save the API with pagination on, and a validation error appears.

With pagination on, the API returns this structure:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "..."
  }
}

next_cursor marks your place in the result set. To get the next page, pass it in the celigo-next-cursor request header. has_more shows whether more pages are available. A request without a cursor returns the first page.

Pagination has these limitations:

  • A cursor expires 24 hours after it's issued.
  • Lookups that enrich each row, which are secondary lookups in an API with more than one lookup, aren't paginated. They run once per row on the current page.
  • Pagination isn't active when you use Run test. Test pagination against the invoke URL.

Design downstream steps for pagination

With pagination on, each request returns one page of results, not the complete result set. Most downstream steps are unaffected, but some logic needs a different design. Design downstream steps on the assumption that only one page is visible at a time. This section applies to any API where pagination is enabled.

Check your downstream logic against these patterns:

Move full-result-set logic outside the paginated call

Don't run grouping, deduplication, or full-set calculations inside a paginated call. These operations need the entire result set, and pagination gives you one page at a time. In these cases, pagination silently produces incomplete or incorrect results instead of failing with an error.

For example, you fetch related items, such as returns, shipments, or line items, that come back unsorted and need grouping by a parent ID. A script that groups all records with the same ID sees only one page's worth, so it returns an incomplete or wrong grouping without an error.

This applies to:

  • Grouping or aggregating by a shared key. Related records can land on different pages.
  • Global deduplication. A duplicate might sit on a page you haven't fetched yet.
  • Full-set calculations. Counts, totals, and existence checks that assume the current data is everything.

If you need pagination, for example because of payload size limits, but you also need the full dataset for one of these cases, don't solve it inside a single API call. Instead:

  1. Have each page write its records to an intermediate store, such as a file or staging table, instead of processing them directly.
  2. Track completion with the has_more field in each response. Keep paging while has_more is true, and stop when it's false. Pass the returned next_cursor value in the celigo-next-cursor request header to get the next page.
  3. When paging is complete, run the aggregation, grouping, or ranking logic as a separate step against the accumulated data. For example, trigger a second linked API after the first completes instead of doing the work inline in the paginated API.

The aggregation logic must run outside the single paginated call. Once you commit to one page at a time, there's no way to do it inline.

Use create-or-update logic for multi-page entities

Some destination records are built from multiple source records that can land on different pages. An always-create downstream step produces duplicate or incomplete destination records, so use a create-or-update pattern instead.

For example, you sync orders from a source system, such as Shopify, into one summary record per customer in a destination system, such as NetSuite. If Customer A has one order on page 1 and another on page 3, page 1 shouldn't create the summary and page 3 shouldn't create a second one. Page 3 must find the existing summary and update or append to it.

This applies to:

  • Roll-up or summary records. Built from detail-level records.
  • Running totals or reconciliation counters. Sums or counts that accumulate across records.
  • The same logical entity on multiple pages. Any case where one entity can appear on more than one page.

To design around it:

  • If the destination system exposes a composite or upsert-style endpoint that checks whether the record exists and then creates or updates it, use that as a single import step. This is the simplest option.
  • If it doesn't, use a lookup step to check whether the record exists, followed by an import that branches to create or update based on the lookup result.
  • If the consumer of your API handles the create-or-update decision itself, that is, the destination is a third-party system outside API builder, the logic must live in the consumer. API builder can guarantee only that it returns correct per-page data, not that the consumer's writes are idempotent. Tell consumers of your API this explicitly.

Leave single-page operations unchanged

Steps that operate within a single page need no special handling and work exactly as they do without pagination. Examples include enriching each record with a lookup and expanding a nested array one-to-many. A lookup isn't paginated, even when the API's primary data source is. It fetches what it needs for the records currently being processed, page by page.

The dividing line is simple. If the logic needs only the current page to produce a correct result, pagination changes nothing. If it needs the full result set, use the same write-to-an-intermediate-store approach as for grouping and deduplication: page through while tracking has_more, then process the accumulated data in a separate step.

What to avoid

  • Assuming has_more is false, or that you've seen everything, before you've paged through the full result set. You'd process an incomplete dataset as if it were complete.
  • Using an always-create import for a destination record that can be built from source records on more than one page. This produces duplicate or incomplete destination records.
  • Adding accumulate-then-process steps where downstream logic needs only the current page. This adds overhead without improving accuracy.
  • Enabling pagination without checking whether any downstream step depends on seeing the full result set at once. Doing so risks silently breaking that step's logic.

Handle offline connections

Immediate error for offline connections controls what happens when a connection the API uses is offline. The setting applies only to APIs built in API builder, not to flows.

State Behavior
Selected The API returns HTTP 500 immediately if any connection it uses is offline, including connections on branches the current request doesn't run.
Cleared When a request reaches a step that uses an offline connection, the API checks the connection every 60 seconds and continues if it comes back online before the API times out.

New APIs have the setting selected. Existing APIs might have it cleared, so check it on any API that should fail fast.

New APIs have this setting selected. APIs created earlier can have it cleared. Select the setting when callers need a fast, predictable response, such as a storefront or partner system that can fail over or retry later. Clear it when callers can wait out a short outage. The wait never exceeds the API timeout. Remove connections the API no longer uses, because with the setting selected, an offline connection on an unused branch fails every request.

This setting doesn't bring connections back online. integrator.io checks offline connections about once an hour and refreshes tokens when the connection type supports it. After six failed attempts, the connection stays offline until you fix it, and reconnection can take up to an hour. See Fix an offline connection.

If requests fail because a connection is offline, see Troubleshoot APIs.

Turn on validation

Select Enable request/response validation to check every API request and response against the schemas defined for this API. Validation is off by default, including for new APIs. While it's off, API builder doesn't reject any request or response. For what validation checks and what callers receive, see Validate API requests and responses in API builder.