---
title: "Read the capture region"
method: GET
path: "/v1/vision/region"
tags: ["Capture"]
---

# Read the capture region

`GET /v1/vision/region`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/vision/region`
- Auth: HTTP bearer

The capture region VisionPiper holds (`vision_region_get`): the rect,
the display it sits on, its generation, whether the border indicator is
showing and whether a recording is running. `status` is `no_region` when
no region is stored, and `region` / `display_id` are then absent.

Refusals use the `precondition_failed` envelope with a typed `reason`
(`visionpiper_unavailable`), so a caller classifies instead of parsing
the message.

## Response `200`

The current capture region state

- VisionRegionState: The capture region VisionPiper holds. `region` and `display_id` are absent when `status` is `no_region`; `indicator_visible` is absent when VisionPiper does not report it.
  - `status` 'ready' | 'no_region' | 'region_set', required
  - `generation` integer, required: Region generation; moves every time the region changes.
  - `recording` boolean, required: Whether a recording is running.
  - `selection_pending` boolean, required: Whether the drag-to-select overlay is waiting for the user.
  - `region` object: The applied rect, in points from the display's top-left.
    - `x` number, double, required
    - `y` number, double, required
    - `width` number, double, required
    - `height` number, double, required
  - `display_id` integer: CGDirectDisplayID the region sits on.
  - `indicator_visible` boolean: Whether the region's border indicator is showing.

## Other responses

- `412`: VisionPiper is not reachable

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)