Skip to main content
Get API Key

Create Query

POST 
/v2/auto/queries
Plan Access
All plans, billed per query in credits
Data Recency
Continuous evaluation against live data
Rate Limit
60 to 120 RPM by plan

Create and activate a conditional query.

Required Sequence (Enforced)​

Call POST /v2/auto/queries/validate immediately before create.

Lifecycle after create:

  1. POST /v2/auto/queries/{queryId}/cancel while status is active.
  2. DELETE /v2/auto/queries/{queryId} only when status is terminal (triggered, expired, cancelled, failed).

Allowed action types (API key mode): webhook, notify, telegram_bot, llm.

Cost​

Simulation-driven estimate (reference values):

  • baseline: 5 credits ($0.0725)
  • fast call: +5 credits (+$0.0725)
  • expert call: +18 credits (+$0.261)

Auth​

Required header:

x-elfa-api-key: <api_key>

Request Example​

{
  "query": {
    "conditions": {
      "AND": [
        {
          "source": "price",
          "method": "current",
          "args": { "symbol": "BTC" },
          "operator": ">",
          "value": 100000
        }
      ]
    },
    "actions": [
      {
        "stepId": "step_1",
        "type": "notify",
        "params": { "message": "BTC crossed target" }
      }
    ],
    "expiresIn": "24h"
  },
  "title": "BTC breakout alert",
  "description": "Notify when BTC is above 100k"
}

Response Example (201)​

{
  "queryId": "a12d20ff-6cb2-433e-afed-cc2e6a0380b6",
  "status": "active",
  "estimatedCredits": 116,
  "simulationLlmCallsEstimate": {
    "conditionCallsUpperBound": 1,
    "actionCallsUpperBound": 0,
    "conditionCallsBySpeed": {"fast": 1, "expert": 0, "adaptive": 0},
    "actionCallsBySpeed": {"fast": 0, "expert": 0, "adaptive": 0},
    "autoActionCallsBySpeed": {"fast": 0, "expert": 0, "adaptive": 0}
  }
}

Best practice: call validate first, then create. After creation, wire notifications (webhook, telegram_bot, or SSE) to a background runner.

Request​

Responses​

Ok