Test a proposed site
Supply a location, business concept and operating assumptions. Receive a saved forecast with downside, base and upside estimates.
Developer sheet · API v1Models, records, provenance
Developer preview
The economy, in your workflow.
Run a site scenario, retrieve its forecast, or bring a business list into your own tools. The API uses the same underlying model as Economic Twin.
API keys are not available yet. Register your interest while access is prepared.
Example requestPOST · simulation
{
"concept": "sandwich shop",
"naics": "722513",
"lon": -117.40954,
"lat": 47.70011,
"avg_ticket": 14,
"months": 36,
"radius_km": 6
}A saved run ID connects the forecast, assumptions and monthly tables.
One core, more ways to use it
From a question to something you can use.
Keep the model inside your own research, planning or customer experience. Results retain their uncertainty and source context.
Keep the same record
Return to the exact saved run for its monthly revenue, staffing, category match and warnings.
Work with business lists
Create a list from a prompt or structured filters, then retrieve its CSV, PDF parts or map points.
Interface reference
Small requests. Useful results.
Create and manage API keys in your account with a current Professional, Team or Enterprise plan. Inspect your capabilities for the scopes and limits available to that key.
| Endpoint | Purpose | Key scope |
|---|---|---|
GET/api/v1/capabilities | Your available scopes and request limits | Any valid API key |
POST/api/v1/simulations | Create a site simulation and return its saved run ID | simulations:write |
GET/api/v1/simulations/{run_id} | Read your saved simulation; select a report section | simulations:read |
POST/api/v1/datalists | Create a business list from a prompt or filters | datalists:write |
GET/api/v1/datalists/{list_id}/csv | Download the list as a streamed CSV | datalists:read |
GET/api/v1/datalists/{list_id}/pdf?part=1 | Download one PDF part | datalists:read |
GET/api/v1/datalists/{list_id}/points | Retrieve a bounded set of map points | datalists:read |
Authentication
A key for your account.
Send your API key in the Authorization header. Keep it on your server, never in a public web page or a URL. Read and write scopes are separate; saved runs and lists belong to your account.
curl "$API_BASE/api/v1/capabilities" \
-H "Authorization: Bearer $API_KEY"Saved results
Read the part you need.
The default response is a compact summary. Request monthly, yearly, pnl, staffing, schedule, cohort, warnings or ledger with the section parameter.
curl "$API_BASE/api/v1/simulations/$RUN_ID?section=monthly" \
-H "Authorization: Bearer $API_KEY"Business data
Bring a specific market into focus.
Use a clear business-type query, or pass filters directly. The machine API uses a fixed planner; it does not accept a caller-selected language model.
curl "$API_BASE/api/v1/datalists" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "insurance premium finance companies",
"filters": {
"type_phrases": ["insurance premium finance company"],
"states": ["WA"]
}
}'Keep the meaning with the numbers.
- Revenue forecasts and synthetic purchases are modeled outputs. They are not observed customer transactions.
- Keep the saved warnings and assumptions with any result you show to others.
- Large requests have limits. Read your capabilities response before scheduling a batch.
- A busy worker returns HTTP 429 and a Retry-After header. Retry later rather than submitting repeated parallel jobs.
- HTTP 401 means authentication is required; 403 means the key lacks access; 404 means the requested resource is unavailable to your account.
Build with Economic Twin
Tell us what you want to connect.
Start with a free account, then choose Professional, Team or Enterprise for API access. Manage scoped keys and exploration credits from your account.