Skip to main content

​
The sandbox

Every account starts on the sandbox plan, and you need no card for it. With a sandbox key you can read 10 companies through every endpoint, the MCP server and the bulk sample: MSFT, AAPL, NVDA, AMZN, GOOGL, META, NFLX, CVX, JPM and SONY. They are the companies in the examples on numi.sh and in these docs. Among them are a bank, JPMorgan Chase, and a foreign filer, Sony, which reports in yen on a 20-F. Between them they have business, product and geographic axes, so you can build against each kind before you pay. On both plans, you can search every company. If you ask for any other company with a sandbox key, the response is status 403 with code sandbox_restricted. The tickers of the sandbox companies are in the error message and in the sandbox_companies field.

​
Requests and the limits

REST requests and MCP tool calls count toward the same limits, and the daily count is reset at midnight UTC. The response to a request over a limit has status 429 and a Retry-After header. See rate limits.

​
Upgrading and cancelling

Choose Upgrade on the account page to pay through Stripe Checkout. Stripe sells the plan as merchant of record. It adds the local tax that applies where you are and may show the price in your own currency. Your account is on Builder as soon as Stripe confirms the payment, which takes a few seconds. Your keys stay valid, and from then on you can read every company with them. Cancel at any time from the billing portal, which the account page links to. The plan stays active to the end of the month you paid for. After that, the account is on the sandbox plan, and with its keys you can read the sandbox companies only.

​
On-demand extraction

On the Builder plan, you can ask numi to extract the filings of a company with POST /v1/companies/{ref}/extract:
  • When numi has extracted the company’s filings already, the response is 200 with status: done and the company.
  • Otherwise numi queues the request, and the response is 202 with status: queued and request_id, the integer id of the extraction request. This request_id is not the meta.request_id of the response. The company’s data will be in the API after the next daily run of the queue.
  • If you ask again for a company that is already queued or being extracted, the response has the same request_id.
  • You can ask for a company that is not in the API yet by its CIK, the SEC’s Central Index Key, as cik: and the digits.
On the sandbox plan the response is 403 plan_required.