---
title: "Well lifecycle state availability"
method: GET
path: "/v1/well-lifecycle/states"
tags: ["Well Lifecycle"]
---

# Well lifecycle state availability

`GET /v1/well-lifecycle/states`

Returns customer-safe lifecycle availability statuses by state. This endpoint
classifies states as available, partial, repair_required, or unavailable so
clients do not mistake missing lifecycle coverage for valid zero data.

## Query parameters

- `states` string
- `api_limit` integer
- `include_samples` boolean

## Response `200`

Lifecycle state availability list

- object
  - `status` string
  - `data` object
    - `generated_at` string, date-time
    - `count` integer
    - `states` WellLifecycleStateAvailability[]
      - `state` string
      - `status` 'available' | 'partial' | 'repair_required' | 'unavailable'
      - `validation_status` string
      - `success` boolean
      - `reasons` string[]
      - `metrics` object
        - `permit_apis` integer
        - `production_matches` integer
        - `exact_match_rate_pct` number
        - `clean_permit_to_production_rate_pct` number
        - `chronology_error_rate_pct` number
      - `production_window` object, nullable
      - `scope` object
        - `api_limit` integer, nullable
        - `bounded` boolean
      - `thresholds` object, nullable
      - `caveats` string[]
      - `samples` object, nullable
      - `summary` WellLifecycleStateSummary
        - `status` 'summary_available' | 'summary_not_built' | 'not_promoted'
        - `summary_wells` integer
        - `production_window` object, nullable
          - `first_production_month` string, date, nullable
          - `latest_production_month` string, date, nullable
        - `cumulative` object, nullable
          - `oil_bbl` number, nullable
          - `gas_mcf` number, nullable
          - `water_bbl` number, nullable
          - `boe` number, nullable
        - `coverage_statuses` object
        - `frac_focus` object
          - `matched_wells` integer
          - `match_rate_pct` number, nullable
          - `latest_job_start_date` string, date, nullable
        - `summary_generated_at` string, date-time, nullable
    - `meta` object

## Other responses

- `400` — Invalid state code
- `401` — Unauthorized
- `403` — Enterprise plan required
- `500` — Unexpected server error. Retry transient failures with bounded backoff and retain the request ID when contacting support.

---

[API](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1.md) · [All operations](https://skmtc.net/oilpriceapi/apis/oil-price-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/oilpriceapi/oil-price-api-v1/revisions/5a5ce424cacc/schema)