Screen a site with public evidence

Resolve a location, create a site, and run an assessment that abstains when the public record is insufficient.

Use Gridstate to resolve a location, collect relevant public evidence, and measure screening friction for a proposed large load.

Before you begin

Complete the API quickstart, then keep GRIDSTATE_API_BASE and GRIDSTATE_API_KEY available in your shell.

A screening result is not a capacity result

The assessment never reports available capacity, deliverable megawatts, engineering feasibility, upgrade cost, schedule, or tariff eligibility. Only a serving utility can establish those facts.

Resolve the location

Start with a GeoJSON point. Coordinates use longitude first:

curl -X POST "$GRIDSTATE_API_BASE/v1/service-territory-resolutions" \
  -H "Authorization: Bearer $GRIDSTATE_API_KEY" \
  -H "Gridstate-Version: 2026-08-24" \
  -H "Content-Type: application/json" \
  -d '{"location":{"type":"Point","coordinates":[-97.0412,32.9014]}}'

The response contains serving-utility candidates. Boundary locations and coarse geometry can return multiple candidates instead of one unsupported conclusion.

Create a tenant-scoped site

Describe the location and proposed load:

curl -X POST "$GRIDSTATE_API_BASE/v1/sites" \
  -H "Authorization: Bearer $GRIDSTATE_API_KEY" \
  -H "Gridstate-Version: 2026-08-24" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "location": {"latitude": 32.9014, "longitude": -97.0412},
    "requestedPeakLoadMw": 120,
    "targetInServiceDate": "2029-06-01",
    "loadProfile": "flat",
    "redundancy": "n_plus_1"
  }'

You can also provide a ramp profile, on-site generation, energy storage, and custom load characteristics. See the site endpoint reference for the complete schema.

Start and poll the assessment

Assessments run asynchronously. Reusing an idempotency key with a different request returns 409 Conflict.

curl -X POST \
  "$GRIDSTATE_API_BASE/v1/sites/$SITE_ID/assessments" \
  -H "Authorization: Bearer $GRIDSTATE_API_KEY" \
  -H "Gridstate-Version: 2026-08-24" \
  -H "Idempotency-Key: $(uuidgen)"

The API returns 202 Accepted with an operation ID. Poll the operation until it completes:

curl "$GRIDSTATE_API_BASE/v1/operations/$OPERATION_ID" \
  -H "Authorization: Bearer $GRIDSTATE_API_KEY" \
  -H "Gridstate-Version: 2026-08-24"

Read the result and its abstention state

Fetch the completed assessment:

curl "$GRIDSTATE_API_BASE/v1/assessments/$ASSESSMENT_ID" \
  -H "Authorization: Bearer $GRIDSTATE_API_KEY" \
  -H "Gridstate-Version: 2026-08-24"

Read abstained before score:

{
  "readiness": {
    "score": 0,
    "classification": "high_friction",
    "metric": "non_capacity_screening_friction",
    "abstained": true,
    "abstentionReason": "Required public evidence did not resolve."
  }
}

An abstained score of zero is not a good score

When abstained is true, the assessment declined to score the site. The zero does not mean low friction or high readiness.

Interpret the evidence bundle

The assessment groups evidence by decision surface:

Field	What it contains
`utilityCandidates`	Utilities that may serve the location
`relevantQueueRecords`	Nearby or jurisdiction-relevant queue evidence
`relevantTransmissionProjects`	Reported transmission work with source locators
`tariffCandidates`	Public tariff evidence that may apply
`marketSignals`	Published market and operating context
`risks` and `nextActions`	Evidence-backed follow-up work, not utility conclusions

Each queue and transmission record retains its source locator and quality flags.

Check whether the geography is supported

Site-level evidence is currently a Texas pilot. It includes ERCOT queue and transmission tracking, PUCT service-territory and docket evidence, and the Oncor retail delivery tariff.

Call /v1/data-coverage before screening another geography. The assessment abstains when required evidence is missing.