Limits and errors

Each Analyst or Pro account gets a daily allowance of API calls, and a limit on how fast calls can arrive. This page covers what counts as a call, the headers that track your allowance, filings being prepared, and every error.

Daily allowance

The allowance depends on the plan:

The count resets at midnight UTC. All of an account's keys share one allowance, separate from the MCP server's, and API calls never spend credits.

When the day's calls run out, the API answers 429 until midnight UTC, with a Retry-After header that counts the seconds to the reset.

Rate limit

Up to 20 calls can arrive at once, then 5 a second. Past that, the API answers 429 with a Retry-After header that says how many seconds to wait.

What counts as a call

Every call the limits let through counts once, even when the answer is an error like a 404 for a missing table. These calls don't count:

• A call refused for its key (401) or its plan (403).
• A 429, whether from the rate limit, the limit on preparing filings, a busy SEC, or a history or AI names that would take more calls than you have left.
• A 202 while SECSift prepares a filing.
• A 500 or 502, when SECSift fails to answer.
• A call whose path names no endpoint, or carries a malformed part, like an accession number in the wrong format.

Two kinds of calls count as more than one:

• Table history: A history with a limit above 12 counts as 2 calls, and the second is charged only when the history comes back.
• AI table names: 2 calls for each table in the filing, so Apple's FY2025 10-K, with 46 tables, costs 92 calls.

When a history or a filing's names would take more calls than you have left today, the API answers 429 without running. That 429 has no Retry-After header, since only midnight UTC brings more calls.

Allowance headers

Every answer past the key check carries three headers, so a script can pace itself:

• X-RateLimit-Limit: Your daily allowance.
• X-RateLimit-Remaining: The calls you have left today.
• X-RateLimit-Reset: When the count resets, in Unix seconds.

Here's how the headers look on a Pro account's answer:

x-ratelimit-limit: 5000
x-ratelimit-remaining: 4793
x-ratelimit-reset: 1793059200

Call /usage for the same numbers in JSON. A call to /usage counts too.

Filings being prepared

A filing SECSift hasn't read before takes a few seconds to prepare. Until the filing's ready, the endpoints that read the filing answer 202 with a Retry-After header in seconds and this body:

{
  "status": "processing",
  "message": "This filing is being prepared. Try again in a few seconds.",
  "retry_after": 10
}

Call again after that many seconds. The next answer can be the filing, another 202, or a 422 when SECSift can't read the filing. A 202 doesn't count as a call. A compare can take two rounds, one for each filing.

An account can start preparing 10 filings at once, then 4 a minute. Past that, the API answers 429 with a Retry-After header until you can start more. A filing SECSift can't read, like a scanned PDF, answers 422 for the next 10 minutes.

A made-up accession number answers 202 at first, then 404.

Retries

A script that waits out short 202 and 429 answers, and stops on anything else, covers most cases. In Python:

import os
import time
import requests

KEY = os.environ["SECSIFT_KEY"]

def get(path):
    while True:
        r = requests.get(
            "https://api.secsift.com/v1" + path,
            headers={"Authorization": f"Bearer {KEY}"},
        )
        wait = int(r.headers.get("Retry-After", 0))
        if r.status_code in (202, 429) and 0 < wait <= 60:
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()

The script gives up on a wait of more than a minute, like the wait for the day's allowance to reset.

Errors

An error answers with a JSON body that gives the error's type and a message:

{
  "error": {
    "type": "not_found",
    "message": "No company ZZZZ."
  }
}

Here's every error status the API answers:

Each message says what went wrong. A section the filing doesn't have answers 404 with the filing's sections in the message.