ATLAS API – Size Parameter Update

Overview

As part of ongoing improvements to performance and security, ATDW will introduce a cap on the size parameter in the ATLAS Search API.

From June 2025 release, the maximum number of profiles that can be requested in a single call will be 5,000.

Requests exceeding this limit will return a:

HTTP 400 Bad Request
    {
        "error": "Invalid 'size' parameter: must be 5,000 or less."
    }

To retrieve more than 5,000 profiles, pagination must be used.

This page provides implementation guidance and answers to common questions.

Implementation Guide

1. Check your current API usage

Review your integration for any calls using size values greater than 5,000. For example:

/products?size=100000&pge=1

2. Apply pagination

If more than 5,000 profiles are needed, implement pagination by combining the size and pagination parameters:

/products?size=5000&pge=1
/products?size=5000pge=2

3. Use random seeded search (optional)

To retrieve a consistent yet randomized result set across pages, use the order=rand_[seed] parameter:

/products?size=5000&pge=1&order=rand_myvalue
/products?size=5000&pge=2&order=rand_myvalue

4. Add error handling

Ensure your integration handles HTTP 400 errors with the message "size must be 5000 or less" gracefully.

Frequently Asked Questions (FAQ)

Will this change affect me?

This change will primarily affect those making API calls that request more than 5,000 profiles per page. For example:

/products?size=100000&pge=1

However, most distributors use delta updates (e.g. /products?delta=2025-04-28) daily or weekly to retrieve only updated content. These requests usually return far fewer than 5,000 profiles, even when the size value is larger. For example:

/products?size=10000000&pge=1&delta=2025-04-28

Although these large-size requests may not exceed 5,000 profiles in practice, the new cap still applies and may trigger an error. Distributors should update their integrations to accommodate pagination if needed.

What if I don't currently use the size parameter?

If you do not specify a size parameter today, the API defaults to returning 10 profiles per page. There is no impact to your existing integration.

However, if you need to retrieve more than 10 profiles per call in the future, you will need to specify a size value (up to 5,000) and implement pagination if necessary.

Why is ATDW making this change?

Large single-call requests place unnecessary load on the system and increase our exposure to automated attacks. Limiting the size parameter improves performance and aligns with cybersecurity best practices.

What if I need all profiles?

You can still access all profiles — just in smaller batches using pagination.

How does this affect overnight batch downloads?

Distributors using scheduled delta updates (daily, weekly) typically retrieve a smaller number of records. If the delta update returns fewer than 5,000 profiles, no change is needed.

If the delta update returns more than 5,000 profiles, pagination should be used. For example:

/products?key=****&delta=2025-04-28&size=5000&pge=1
/products?key=****&delta=2025-04-28&size=5000&pge=2
/products?key=****&delta=2025-04-28&size=5000&pge=3

When will this change take effect?

The change will go live in the late June 2025 release.

Where can I get help?

Contact [email protected] for assistance.