Run a task

POST /api/v1/predict — run one Ostra Decision task (failure triage, test impact or selector survival) and get its decision.

POSThttps://ostra.testrelic.ai/api/v1/predict

Runs one Ostra Decision task (failure triage, test impact or selector survival) and returns its decision.

Send model: "ostra-lite", the task, and that task’s input. The answer is in output, in the shape for the task. An identical task and input within 24 hours is answered from cache, for free.

Auth
Authorization: Bearer $OSTRA_API_KEY. Needs a Full-access key.
Rate limit
Counts against your workspace's requests per minute.
Cost
Triage $0.50 per 1M failures; test impact $2.00 per 1M requests; selector survival $0.25 per 1M locators. Output is free. Cached answers and errors cost nothing; a defer answer is billed.
Over MCP
Same operation as the ostra_triage_failure tool.
curl https://ostra.testrelic.ai/api/v1/predict \
  -H "Authorization: Bearer $OSTRA_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "ostra-lite",
    "task": "triage",
    "input": {
      "test_id": "checkout.spec.ts > applies coupon",
      "run_id": "gha-18241",
      "context": {
        "framework": "playwright",
        "capture_level": "full",
        "error_message": "TimeoutError: locator.click: Timeout 30000ms exceeded.\n  waiting for locator('\''#apply-coupon'\'')",
        "action": "click",
        "locator": {
          "strategy": "css"
        },
        "diff": {
          "files_changed": 3,
          "lines_added": 41,
          "lines_removed": 12,
          "touches_test_file": false,
          "touches_selector_file": false,
          "locator_values_removed": false
        },
        "dom": {
          "locator_found": true
        },
        "memory": {
          "runs_50": 40,
          "flake_rate_50": 0.15,
          "failed_count_50": 6,
          "signature_repeat_count": 5
        }
      }
    }
  }'
Headers
x-request-id
req_01JDXK4M7Q2N8R5T6V9W3Y1Z0A
ostra-ratelimit-requests-limit
600
ostra-ratelimit-requests-remaining
599
ostra-ratelimit-requests-reset
42
ostra-balance-remaining-usd
24.9999995
{
  "id": "req_01JDXK4M7Q2N8R5T6V9W3Y1Z0A",
  "model": "ostra-lite@v.beta.5",
  "task": "triage",
  "cached": false,
  "billed": {
    "units": 1,
    "costNano": 500,
    "costUsd": "0.0000005"
  },
  "output": {
    "decision_id": "dec_5b0c9e2a7f3d4e18a6b2c9d0e1f4a7b3",
    "task": "triage",
    "decision": "flaky",
    "value": "flaky",
    "p": 0.83,
    "probabilities": {
      "flaky": 0.83,
      "product_bug": 0.06,
      "test_bug": 0.05,
      "environment": 0.04,
      "selector_drift": 0.02
    },
    "threshold": 0.6,
    "defer_reason": null,
    "decided_by": "model",
    "rule": null,
    "model": {
      "release": "v.beta.5",
      "version": "1.4.0",
      "content_hash": "sha256:3f9a1c07d2e4b8a6",
      "gate_passed": true
    },
    "test_id": "checkout.spec.ts > applies coupon",
    "run_id": "gha-18241",
    "error_class": "timeout",
    "error_class_source": "error_message"
  }
}

Request body

  • modelstringRequired

    Always ostra-lite (Ostra Decision).

    Valueostra-lite
  • taskstringRequired

    Which task to run.

    One oftriagetest_impactselector_survival
  • inputobjectRequired

    The task’s input. Unknown fields are rejected. See the three task shapes below.

Task input and output

input and output depend on task. Unknown input fields are rejected, and every evidence field is optional: send what you have.

input for triage

  • test_idstring

    Your identifier for the failing test, echoed back in the answer. Use a stable name, e.g. checkout.spec.ts > applies coupon.

    1–512 chars
  • run_idstring

    Your identifier for the CI run, echoed back.

    1–512 chars
  • contextobjectRequired

    Evidence about the failure. Every field is optional except that error_class or error_message must be present. Missing evidence is treated as missing, never as zero, so send what you have.

    Show 10 child fields
    • idstring

      Your own id for this failure record.

      1–512 chars
    • frameworkstring

      Test framework that produced the failure.

      One ofplaywrightcypressjestselenium
    • capture_levelstring

      How much of the failure was captured (trace, DOM, network): full, partial or none.

      One offullpartialnone
    • error_classstring

      Normalized class of the error. Required unless you send error_message.

      One oftimeoutlocator_not_foundstale_elementstrict_mode_violationassertion_mismatchnetwork_errorscript_errorunmapped
    • error_messagestring

      The raw error text. Used only to derive error_class when you don’t send one; the answer reports which you used in error_class_source.

      0–8,000 chars
    • actionstring

      The step that failed.

      One ofclickfillnavigateassertwait_forapi_callscreenshot
    • locatorobject

      The locator the failing step used.

      Show 1 child field
      • strategystring

        How the element was located.

        One ofcssxpathtest_idtextrolenone
    • diffobject

      The code change the run tested.

      Show 6 child fields
      • files_changedinteger

        Files changed in the commit or pull request under test.

        0 to 1,000,000
      • lines_addedinteger

        Lines added.

        0 to 1,000,000
      • lines_removedinteger

        Lines removed.

        0 to 1,000,000
      • touches_test_fileboolean

        The change edits a test file.

      • touches_selector_fileboolean

        The change edits a page object, locator map or other file that defines selectors.

      • locator_values_removedboolean

        The change removes or renames a locator value (an id, test id, class or text) that the test uses.

    • domobject

      What the page looked like at failure time.

      Show 1 child field
      • locator_foundboolean

        The locator still matched an element in the captured DOM.

    • memoryobject

      This test’s recent history, over its last 50 runs at most.

      Show 6 child fields
      • runs_50integer

        Runs in the window.

        0 to 50
      • failed_count_50integer

        Failed runs in the window.

        0 to 50
      • passed_on_retry_50integer

        Runs that failed and then passed on retry.

        0 to 50
      • consecutive_failures_50integer

        Failures in a row up to this one.

        0 to 50
      • flake_rate_50number

        Share of runs in the window that were flaky, 0–1.

        0 to 1
      • signature_repeat_countinteger

        How many times this exact error signature has been seen before.

        0 to 1,000,000

output for triage

  • decision_idstring

    Unique id of this decision: dec_ and 32 hex characters.

  • taskstring

    The task that answered.

    One oftriagetest_impactselector_survival
  • decisionstring

    The answer: one of the task’s classes, likely_flaky (triage only), or defer when the model isn’t confident enough.

  • valuestring or null

    The same answer, or null when the decision is defer.

  • pnumber

    Probability of the top class, 0–1.

  • probabilitiesmap of numbers

    Probability of every class, keyed by class.

  • thresholdnumber

    The confidence the top class must reach for a firm answer. Below it, the answer is defer (or likely_flaky).

  • defer_reasonstring or null

    Why the answer is defer; null otherwise. insufficient_evidence means the request carried nothing about this test or locator.

    One ofbelow_thresholdmodel_gate_failedinsufficient_evidence
  • decided_bystring

    rule when an unambiguous environment rule answered (see rule). The probabilities are still the model’s.

    One ofmodelrule
  • rulestring or null

    The rule that answered, when decided_by is rule. A rule answer is always environment.

    One ofbrowser_not_installedhost_missing_dependencieswebdriver_session_not_createdport_in_usedisk_full
  • modelobject

    The model release that answered.

    Show 4 child fields
    • releasestring

      Ostra Decision release, e.g. v.beta.5.

    • versionstring

      Version of this task’s model in that release.

    • content_hashstring

      Content hash of the model that answered.

    • gate_passedboolean

      The model passed its release quality gate. When false, every answer is defer with model_gate_failed.

  • test_idstring or null

    Your test_id, echoed.

  • run_idstring or null

    Your run_id, echoed.

  • error_classstring

    The error class the model used.

    One oftimeoutlocator_not_foundstale_elementstrict_mode_violationassertion_mismatchnetwork_errorscript_errorunmapped
  • error_class_sourcestring

    request when you sent error_class, error_message when it was derived from your message.

    One ofrequesterror_message

Response

  • idstring

    Request id, the same as the x-request-id header.

  • modelstring

    The model and release that answered, e.g. ostra-lite@v.beta.5.

  • taskstring

    The task you ran.

  • cachedboolean

    true when the answer came from the 24-hour cache (and cost nothing).

  • billedobject

    What this request cost. Cached answers cost 0.

    Show 3 child fields
    • unitsinteger

      Billable units: 1 per failure (triage), 1 per request (test impact), 1 per locator (selector survival). 0 for a cached answer.

    • costNanointeger

      Cost in nano-dollars (1 USD = 1,000,000,000).

    • costUsdstring

      Cost in USD as an exact decimal string, e.g. "0.0000005".

  • outputobject

    The task’s answer. Shapes: triage, test impact and selector survival below.

Response headers

  • x-request-idstring

    Id of this request (req_ + 26 characters). Quote it to support.

  • ostra-ratelimit-requests-limitinteger

    Your workspace’s requests-per-minute limit.

  • ostra-ratelimit-requests-remaininginteger

    Requests left in the current minute.

  • ostra-ratelimit-requests-resetinteger

    Seconds until the current minute ends and the count resets.

  • ostra-balance-remaining-usdstring

    Workspace credit balance after this request, in USD. Approximate under concurrent requests.

Errors

StatusTypeWhen
400invalid_requestThe body isn’t valid JSON or fails validation; param names the field.
413payload_too_largeThe request body is larger than the route allows.
401authentication_errorThe API key is missing, malformed, unknown, revoked or expired.
403permission_errorThe caller’s IP isn’t in the key’s allowlist, or a read-only key called a route that needs full access.
402insufficient_balanceYour credit balance doesn’t cover the request. Nothing is charged.
402spend_limit_reachedThe workspace’s monthly spend limit (scope: "org") or this key’s monthly spend cap (scope: "key") is reached.
429rate_limit_exceededThe workspace’s requests-per-minute limit is reached. Wait Retry-After seconds.
502upstream_errorOstra Decision failed to answer. Nothing was charged.
503service_unavailableToo many requests are updating the workspace balance at once. Nothing was charged; retry after Retry-After (1 s).
504upstream_timeoutOstra Decision didn’t answer within 10 seconds. Nothing was charged.

Every error has the same envelope and a request_id. See Errors for messages and retry advice.

Was this page helpful?