Guides
On-demand analysis

On-demand analysis

Four per-symbol routes can analyse an asset that is not cached yet: you get 202 and a job to poll instead of a 404.

Routes: /sentiment/{symbol}, /technical/{symbol}, /narrative/{symbol} and /predictions/intraday/{symbol}. The first request for an uncached symbol validates the ticker, queues analysis and adds the asset to your watchlist so it stays fresh.

Case	Response
Cached and fresh	200, data returned
Cached but stale	200 with `meta.stale`; refreshed in the background
Not cached yet	202, queued: poll the status URL
Unknown ticker	404 `SYMBOL_NOT_FOUND`

202 Accepted

HTTP/2 202
Retry-After: 8

{
  "success": true,
  "data": {
    "status": "pending",
    "symbol": "NVDA",
    "job_id": "<job_id>",
    "data_kind": "sentiment",
    "poll_url": "/public/v1/analysis/status/<job_id>",
    "result_url": "/public/v1/sentiment/NVDA",
    "retry_after": 8,
    "message": "Analysis for this asset was not cached yet. …"
  },
  "meta": { "accepted": true, "poll_url": "…", "retry_after": 8 }
}

Poll, then read#

Poll /analysis/status/{job_id} until state is ready (pending → running → ready | failed), then fetch result_url.

Sentiment is generated at once. For technical, narrative and predictions, readiness means sentiment is live; the kind-specific data backfills on its next scheduled run, so those URLs can keep returning 202 until then. The response says so in note.

Caps#

Every new asset joins your watchlist. Adding one beyond your plan’s tracked-asset cap returns 403 WATCHLIST_LIMIT_REACHED; the response states the cap. New-asset triggers have their own per-minute limit (429 ON_DEMAND_RATE_LIMIT).

COT and volatility routes never queue analysis: they return 404 NOT_AVAILABLE_FOR_ASSET when no data exists for the symbol.

Educational market research, not investment advice; not for fully automated trade execution. Questions about the API or the MCP server: support@tradeeasyai.net.