Paging the Slack Web API and handling its per-method rate-limit tiers

What it is

Slack's pagination guide explains that cursor-paginated methods "accept cursor and limit parameters" and that "paginated responses include a top-level response_metadata object that includes a next_cursor when there are additional results to be retrieved." A client passes that value back as the cursor parameter on the next call; "an empty, null, or non-existent next_cursor... indicates no further results," and the guide explicitly warns against inferring completeness from the result count instead. Cursors expire, so "do not persist cursors for hours or days"; a stale or garbled one returns invalid_cursor. The limit maximum is 1000 "subject to change and may vary per method," with 100-200 recommended for well-behaved paging. Slack's rate-limits page groups methods into tiers — roughly "1+ per minute" (Tier 1) up to "100+ per minute" (Tier 4), plus per-method "Special Tier" rules such as chat.postMessage generally allowing about one message per second per channel — all applied "per API method per workspace/team per app." On any HTTP-based API including incoming webhooks, exceeding a limit returns "HTTP 429 Too Many Requests... and a Retry-After HTTP header containing the number of seconds until you can retry," scoped to that method and workspace; other methods and other workspaces are unaffected.

Why it matters

Slack's tiers mean the same client can be well within budget on one method and immediately throttled on another; treating the API as having one global rate limit leads to under- or over-throttling. Fetching an entire large list without pagination is also documented to draw stricter limits on its own.

How to apply

• Always send limit explicitly and check response_metadata.next_cursor after every call, looping until it is empty/absent.
• Track budgets per method, not globally, since tiers and special-case limits (like message posting) are method-specific.
• On 429, read Retry-After and wait exactly that long before calling the same method for that workspace again; other methods remain usable in the meantime.
• For bulk exports (e.g. all users or all channels), paginate with a moderate limit (100-200) rather than requesting the maximum in one call.

def list_all_users(client, limit=200):
    cursor, users = None, []
    while True:
        resp = client.users_list(limit=limit, cursor=cursor)
        users += resp["members"]
        cursor = resp.get("response_metadata", {}).get("next_cursor")
        if not cursor:
            return users

Pitfalls

Stopping pagination when a page returns fewer results than limit, which Slack's docs explicitly call an unsafe signal of completeness. Applying one retry/backoff budget across all Web API methods instead of per method and per workspace, as the tiers require.