---
title: "Start an asynchronous AC study"
method: POST
path: "/api/v1/solver/runs"
tags: ["Network Solver"]
---

# Start an asynchronous AC study

`POST /api/v1/solver/runs`

## Request

- Base URL: `https://askthegrid.com`
- URL: `https://askthegrid.com/api/v1/solver/runs`
- Auth: HTTP bearer

Returns HTTP 202 with a durable run ID. Supply a requestId UUID to safely replay a submission; reuse with different inputs is refused. One scenario with no contingency list runs an AC power flow; multiple scenarios or contingencies fan out through the security-analysis engine. Up to 25,000 solves including each scenario's base case. Positive injection adds generation; negative adds demand. Branch IDs name single-branch contingencies. Ratings use Rate A, taps and shunts are fixed, and the swing bus balances changes. Engine non-convergence is a study result, distinct from an execution failure. Poll getSolverRun and cancel with cancelSolverRun.

## Request body

- object
  - `requestId` string, uuid
  - `modelId` string, uuid, required
  - `scenarios` object[], required
    - `name` string, required
    - `loadScale` number
    - `outages` string[]
    - `injections` object[]
      - `bus` integer, required
      - `mw` number, required
      - `mvar` number
  - `outages` string[]
  - `top` integer

## Response `202`

Success

- object
  - `id` string, uuid, required
  - `modelId` string, uuid, required
  - `modelSha256` string, required
  - `createdAt` string, required
  - `finishedAt` string, nullable, required
  - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled', required
  - `solves` integer, required
  - `input` object, required
    - `requestId` string, uuid
    - `modelId` string, uuid, required
    - `scenarios` object[], required
      - `name` string, required
      - `loadScale` number, required
      - `outages` string[], required
      - `injections` object[], required
        - `bus` integer, required
        - `mw` number, required
        - `mvar` number, required
    - `outages` string[], required
    - `top` integer, required
  - `progress` object, nullable, required
    - `solved` number, required
    - `total` number, required
    - `batchesDone` number, required
    - `batches` number, required
    - `withNewOverloads` number, required
    - `notConverged` number, required
  - `result` union, required
    - object
      - `kind` 'ac', required
      - `study` object, required
        - `engine` string, required
        - `engine_package_version` string, required
        - `converged` boolean, required
        - `settings` object, required
        - `components` object[], required
          - `connected_component` number, required
          - `status` string, required
          - `iterations` number, required
        - `counts` object, nullable, required
          - `buses` number, required
          - `branches` number, required
          - `over_rating` number, required
          - `units_at_limit` number, required
          - `islands` number, required
          - `unsolved_islands` number, required
        - `totals` object, nullable, required
          - `generation_mw` number, required
          - `generation_mvar` number, required
          - `load_mw` number, required
          - `load_mvar` number, required
          - `loss_mw` number, required
        - `voltage` object, nullable, required
          - `band` unknown[], required
            - unknown
          - `below` number, required
          - `above` number, required
          - `lowest` object[], required
            - `number` number, required
            - `name` string, required
            - `base_kv` number, required
            - `voltage_pu` number, required
            - `voltage_kv` number, required
            - `angle_deg` number, required
          - `highest` object[], required
            - `number` number, required
            - `name` string, required
            - `base_kv` number, required
            - `voltage_pu` number, required
            - `voltage_kv` number, required
            - `angle_deg` number, required
        - `buses` object[], required
          - `number` number, required
          - `name` string, required
          - `base_kv` number, required
          - `voltage_pu` number, required
          - `voltage_kv` number, required
          - `angle_deg` number, required
        - `branches` object[], required
          - `id` string, required
          - `from_bus` number, required
          - `to_bus` number, required
          - `rating_mva` number, required
          - `from_mw` number, required
          - `from_mvar` number, required
          - `to_mw` number, required
          - `to_mvar` number, required
          - `loss_mw` number, required
          - `mva` number, required
          - `loading_percent` number, nullable, required
        - `units` object[], required
          - `bus` number, required
          - `mw` number, required
          - `mvar` number, required
          - `qmin_mvar` number, required
          - `qmax_mvar` number, required
          - `voltage_pu` number, required
          - `setpoint_pu` number, required
          - `at_limit` 'max' | 'min', nullable, required
        - `elapsed_seconds` number, required
        - `limits` string, required
    - object
      - `kind` 'grid', required
      - `grid` object, required
        - `engine` string, required
        - `engine_package_version` string, required
        - `token` string, required
        - `solves` number, required
        - `batches` number, required
        - `batches_failed` number
        - `elapsed_seconds` number, required
        - `scenarios` object[], required
          - `name` string, required
          - `base` object, required
            - `outage` string, required
            - `converged` boolean, required
            - `islanded_buses` number, required
            - `over_rating` number, required
            - `new_overload_count` number, required
            - `new_overloads` object[], required
              - …
            - `worst_loading` object, nullable, required
              - …
            - `below_band` number, required
            - `above_band` number, required
            - `new_low_voltage_count` number, required
            - `new_low_voltages` object[], required
              - …
            - `lowest_voltage` object, nullable, required
              - …
          - `counts` object, required
            - `outages` number, required
            - `not_converged` number, required
            - `with_new_overloads` number, required
            - `with_new_low_voltages` number, required
            - `islanding` number, required
          - `worst` object[], required
            - `outage` string, required
            - `converged` boolean, required
            - `islanded_buses` number, required
            - `over_rating` number, required
            - `new_overload_count` number, required
            - `new_overloads` object[], required
              - …
            - `worst_loading` object, nullable, required
              - …
            - `below_band` number, required
            - `above_band` number, required
            - `new_low_voltage_count` number, required
            - `new_low_voltages` object[], required
              - …
            - `lowest_voltage` object, nullable, required
              - …
  - `error` string, nullable, required
  - `assumptions` string[], required

## Other responses

- `400`: The request did not match the contract.
- `401`: Missing or invalid credentials.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds; `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` report the budget. Signed-in sessions and API keys have larger budgets than anonymous callers.

---

[API](https://skmtc.dev/askthegrid/apis/ask-the-grid-api.md) · [All operations](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/llms.txt) · [OpenAPI document](https://skmtc.dev/askthegrid/apis/ask-the-grid-api/revisions/9cd80115e395?raw)