There are two ways to use Marginal AI data in your own tools: connect an AI agent, or call the Enterprise REST API from your own software.
| Agent (MCP) | Enterprise REST API | |
|---|---|---|
| For | Claude, Claude Code, Codex, ChatGPT, Cursor and other MCP clients | Your own applications and data pipelines |
| Address | https:// | https:// |
| Access | Marginal AI sign-in or a personal API key | Company API key |
| Plans | Every plan | Enterprise |
| Guide | Connect your AI agent | OpenAPI reference |
Enterprise REST API: getting a key
Your company admin creates the key in Settings > Company > Company API keys, after accepting the Agent API Terms. Send it with every request:
Authorization: Bearer mai_sk_...Example: events first seen since a given time.
curl -H "Authorization: Bearer mai_sk_..." \
"https://api.marginal-ai.com/api/v1/events/new?since=2026-09-28T00:00:00Z"Endpoints
| GET | Returns |
|---|---|
/ | Corporate and market events, with source links and first-seen timestamps. |
/ | Events first seen since a time you give, for polling. |
/ | One event in full. |
/ | Confirms a ticker or SEC CIK and returns the company’s identifiers. Free. |
/ | A company’s events, by ticker or CIK. |
/ | The event categories and types. Free. |
/ | The industry groups covered. Free. |
/ | One figure exactly as reported to the SEC, with the filing link. |
/ | A reported figure across periods, each linked to its filing. |
/ | The available macroeconomic series. |
/ | Observations of one macroeconomic series. |
Parameters and response formats are in the OpenAPI reference.
Cost and limits
- Event calls use 0.5 Compute Units (CU) and include up to 10 events; each further event costs 0.02 CU (a 50-event page costs 1.3 CU).
- SEC financials and macro calls use 0.5 CU. The three lookups marked Free cost nothing. Failed calls are not charged.
- CU is drawn from your company’s pooled CU. Up to 600 calls a minute and 200,000 calls a day per company.
Monthly event limit (Agent API on self-service plans). Each account can retrieve a set number of distinct events per calendar month: Free 250, Basic 2,500, Intermediate 4,000, Advanced 8,000, Business 10,000 plus 1,000 per extra seat up to 30,000. Enterprise has no monthly limit. Re-reading the same events does not count again, and a company’s keys and members share one count. Over the limit, event calls return an error with the reset date; SEC and macro calls keep working. Responses include monthly_events with used, cap and resets_at.
| Error | Meaning |
|---|---|
401 | Missing or invalid key. |
402 insufficient_balance | No CU left, or the unpaid-overage limit has been reached. |
404 not_found | No such event, company or series. |
429 monthly_ | Monthly event limit reached. The response gives the reset date. SEC and macro calls keep working. |
429 | Rate limit, daily limit or busy. Wait for the time given in the Retry-After header. |
503 | Temporarily unavailable. Try again later. |
Tips
- No need to name Marginal AI. Once connected, your agent uses Marginal AI automatically for company events and news, figures companies reported to the SEC, and economic data. For explanations and comparisons it starts a research question.
- To make it certain, add one standing instruction. In Claude, use Settings > Profile (personal preferences) or your Project’s instructions; in Claude Code, your
CLAUDE.md; in Codex, yourAGENTS.md. Suggested wording: “For company events, SEC-reported financial figures and economic data, use the Marginal AI tools.” - Using Marginal AI in the background (for example “Hey Siri, ask Claude” or scheduled tasks): set the Marginal AI tools to Always allow in your agent, because a background run cannot ask for your approval.
- Siri on iPhone. Say “Hey Siri, ask Marginal AI”. Siri asks what you’d like to know; then ask your question. To skip “Hey Siri”, go to Settings > Accessibility > Touch > Back Tap and set Double Tap to “Ask Marginal AI” (or use the Action button on iPhone 15 Pro and later).
Important
The API describes events, reported figures and macroeconomic data, with links to their sources. It gives no investment advice or ratings and places no orders, and every result carries a notice saying so.
Use is governed by the Agent API Terms, the Enterprise Order Terms and the Data Processing Agreement.
Questions: support@marginal-ai.com
