# MarketLabs intelligence and simulations

URL: https://docs.fxapis.com/guides/marketlabs

> Read a shared market snapshot and queue a private simulation with the same fxapis API key. Simulations are polled. They do not place an order.



> **MarketLabs is coming soon.** It is not available to workspaces yet: until
> it is, its endpoints answer `404 NOT_FOUND` and it does not appear in the
> console. This guide describes how it will work.

MarketLabs is part of fxapis. You use the same dashboard, the same session, and the same API key. A plan that does not include MarketLabs is refused with `402 FEATURE_NOT_IN_PLAN`. A key without the scope is refused with `403 MISSING_SCOPE`.

| Scope             | Allows                                                                        |
| ----------------- | ----------------------------------------------------------------------------- |
| `marketlabs:read` | Intelligence, events, forecasts, performance, usage, and your own simulations |
| `marketlabs:run`  | Queue and cancel your own simulations                                         |

`marketlabs:manage` is not grantable on a key. It belongs to the workspace owner.

Reading intelligence does not start a simulation, and it does not spend a connected account's live-read allowance. A simulation is private to the workspace that created it. Another workspace's id is `404`.

## Read a snapshot [#read-a-snapshot]

```bash
curl "https://api.fxapis.com/v1/marketlabs/markets/EURUSD/intelligence" \
  -H "Authorization: Bearer $FXAPIS_KEY"
```

The body is under `data`, with `asOf`, `freshness` (`fresh` or `stale`), and `baseline` as a decimal string. Times are UTC.

## Queue a simulation [#queue-a-simulation]

Send `Idempotency-Key`. The same key and the same body return the first simulation. The same key and a different body is `409 IDEMPOTENCY_KEY_REUSED`.

```bash
curl -X POST "https://api.fxapis.com/v1/marketlabs/simulations" \
  -H "Authorization: Bearer $FXAPIS_KEY" \
  -H "Idempotency-Key: research-20261104-eurusd-01" \
  -H "Content-Type: application/json" \
  -d '{"instrument":"EURUSD","horizon":"4h","configuration":{"personas":20,"repetitions":3}}'
```

The answer is `202`, with `data.id` and `data.pollUrl`. Poll `GET /v1/marketlabs/simulations/{id}` until `status` is `succeeded`, `failed`, or `cancelled`. `DELETE` cancels a queued simulation and releases its credit. A simulation that has already finished is `409 SIMULATION_NOT_CANCELLABLE`.

`GET /v1/marketlabs/usage` reports `included`, `reserved`, and `used` for the current UTC month. Past the included count, creating one is `402 QUOTA_EXCEEDED`. If MarketLabs cannot accept the request, the answer is `503 MARKETLABS_UNAVAILABLE`. Trading routes are unaffected.

A simulation never places an order. Closing a position is a separate call, with a trading scope, on an account you choose.