POST /run

POST /run and /run/batch

Abstract

/run is the primary free evaluate entry: accept Pine source + bar list, optionally wire request.* data sources, execute via package pynescript.runtime.Runtime (Pro API uses backend.runtime re-export), and return plots/series/events/drawings/alerts. /run/batch runs up to eight scripts on the same OHLCV (AXIS multi-indicator), isolating per-script errors so one failure does not discard siblings. Optional free-tier guards (FREE_TIER_LIMITS, default off) enforce bar/script caps, rate limit, concurrency, and chart/mock-only data (backend/middleware/free_limits.py). Optional L2 webhooks POST last-bar (default) alert() / alertcondition() firings to webhook_url or env ALERT_WEBHOOK_URL (SSRF-safe).

Conceptual model

Rendering…

Interface surface

POST /run

Request (RUN_SCHEMA)

Query ?mode= is accepted when the body omits mode.

Unknown fields → UNKNOWN_FIELDS 400. Empty script/data still checked after schema with NO_SCRIPT / NO_DATA. import and any request. token are compile-ineligible; mode=auto falls back to interpret and keeps libraries on that path.

Bar shape (runtime expectation):

{ "time": 0, "open": 1, "high": 1, "low": 1, "close": 1, "volume": 1 }

Optional bid / ask per bar update runtime bid/ask state.

Success response

{
  "status": "success",
  "plots": [],
  "series": {},
  "plot_meta": {},
  "events": [],
  "drawings": [],
  "alerts": [],
  "script_id": "16hex",
  "run_id": "16hex",
  "count": 0,
  "mode": "compile",
  "auto_backend": "compile",
  "data_source": "chart",
  "alert_forward": {
    "forwarded": 0,
    "failed": 0,
    "filter": "last_bar",
    "url": "https://hooks.example.com/pine",
    "batch": true
  }
}

Errors

POST /run/batch

Request (RUN_BATCH_SCHEMA)

Hard cap: RUN_BATCH_MAX_SCRIPTS = 8 → TOO_MANY_SCRIPTS.

Response

{
  "status": "success" | "partial",
  "results": [ { "id": "…", "status": "success|error", … } ],
  "count": 2,
  "ok": 1,
  "data_source": "chart"
}

HTTP 200 for partial success (per-script errors inside results). Envelope validation failures still 400.

Internals

runtime = Runtime(symbol=str(symbol))
result = runtime.run(script, ohlcv, data_feed=…, data_provider=…, mode=…)

See runtime bridge for bar-loop details and compile mode.

Paths: backend/app.py (run_pine_script, run_pine_script_batch, compile_prewarm, WS /ws/run), backend/middleware/schemas.py, backend/middleware/free_limits.py, backend/alert_forwarder.py.

Invariants and edge cases

1. No API key on these routes — free-tier guards apply only when FREE_TIER_LIMITS is on (see Pro API usage); protect further at the edge if needed.
2. Batch isolates exceptions per script (try/except around runtime.run).
3. Whitespace-only data_source coerced to None → chart default; free paths reject live providers (ccxt/yahoo/…) when FREE_TIER_LIMITS is on.
4. Compile mode may omit alert side effects (alerts: []); use interpret/auto for alerts.
5. Schema rejects extras — clients must not send AXIS-only fields without updating schema.
6. Webhook delivery is best-effort — evaluate still returns status: success if the hook fails; check alert_forward.
7. Structured errors may include error_kind (parse|compile|runtime|data|order|mode), error_type, error_bar. timed_out is set on the HTTP body when Runtime exceeds timeout_seconds.

Worked example

curl -s http://127.0.0.1:5002/run \
  -H 'Content-Type: application/json' \
  -d '{
    "script": "//@version=6\nindicator(\"t\")\nplot(close)",
    "data": [
      {"time": 1, "open": 1, "high": 2, "low": 0.5, "close": 1.5, "volume": 10},
      {"time": 2, "open": 1.5, "high": 2.5, "low": 1.0, "close": 2.0, "volume": 12}
    ],
    "symbol": "TEST:DEMO"
  }'

Failure modes

POST /compile/prewarm

Free readiness hook (same rate/concurrency gates). Body optional:

{ "scripts": ["//@version=6\nindicator(\"x\")\nplot(close)"], "force": false }

Caps at 16 sources. Returns has_numba, builtins_warmed, scripts_ok / scripts_failed, prewarm_ms. Does not execute on OHLCV.

WS /ws/run

When flask-sock is installed: JSON text frames {type: "run", id, script, data, mode?}. Reply {type: "result", …} or {type: "error"}. Ping/pong supported. Same execute_run_payload as HTTP /run.

Alert webhooks (L2)

# Server default (optional)
export ALERT_WEBHOOK_URL=https://hooks.example.com/pine

curl -s http://127.0.0.1:5002/run \
  -H 'Content-Type: application/json' \
  -d '{
    "script": "//@version=6\nindicator(\"a\")\nif bar_index == last_bar_index\n    alert(\"fire\")\nplot(close)",
    "mode": "interpret",
    "webhook_url": "https://hooks.example.com/pine",
    "data": [
      {"time": 1, "open": 1, "high": 2, "low": 0.5, "close": 1.5, "volume": 10},
      {"time": 2, "open": 1.5, "high": 2.5, "low": 1.0, "close": 2.0, "volume": 12}
    ]
  }'

Full engine rules and batch payload shape: Alerts.

See also

• Alerts
• Contract
• Runtime bridge
• App lifecycle