---
title: "Locate In Screenshot"
method: POST
path: "/api/v1/screenshots:locate"
tags: ["Screenshots"]
---

# Locate In Screenshot

`POST /api/v1/screenshots:locate`

## Request

- Base URL: `https://argus.axilio.ai`
- URL: `https://argus.axilio.ai/api/v1/screenshots:locate`
- Auth: API key in header `X-Axilio-Api-Key`
- TypeScript: <https://skmtc.dev/axilioai/apis/argus-2/docs/api/v1/screenshots:locate/post.ts> (a function with typed inputs; its response is checked against the schema)

Find the element a query describes in a screenshot: a point, or an OCR text.

## Request body

- LocateRequest: Argus POST /screenshots:locate request. The caller pre-computes OCR via POST /screenshots:detect (or reuses cached results keyed by frame hash) and passes the text list here. Argus does NOT re-run OCR; the VLM call uses the provided `texts` as grounding context.
  - `image` string, required: Base64 encoded image (PNG or JPEG)
  - `model` string, nullable: VLM model to use; must be one of the models from GET /models. Omit to use the server's configured default. The system prompt is fixed to the element-locator task.
  - `query` string, required: Natural-language target description
  - `texts` TextElementInput[]: Pre-computed OCR text elements. Empty list means Argus skips OCR grounding and asks the VLM to locate from the image alone.
    - `bbox` BoundingBox, required
      - `x1` number, required: Top-left x coordinate
      - `x2` number, required: Bottom-right x coordinate
      - `y1` number, required: Top-left y coordinate
      - `y2` number, required: Bottom-right y coordinate
    - `text` string, required: OCR'd text content

## Response `200`

Successful Response

- LocateResponse: Argus POST /screenshots:locate response. Exactly one of `matched_text_index` or `bbox` is populated when `found` is True. `matched_text_index` indicates the VLM grounded its answer to a specific OCR text element (pixel-accurate bbox available via the original `texts` list). `bbox` is a free-form VLM bbox.
  - `bbox` LocateBBox: Pixel-space bbox returned by the VLM for the located element.
    - `height` integer, required: Height in pixels
    - `width` integer, required: Width in pixels
    - `x` integer, required: Top-left x in image pixels
    - `y` integer, required: Top-left y in image pixels
  - `completion_tokens` integer: Completion (output) tokens the model billed for this call
  - `confidence` number, required: Model self-reported confidence
  - `cost_microdollars` integer, required: Provider-reported cost in microdollars
  - `found` boolean, required: Whether the VLM located the target
  - `latency_ms` integer, required: End-to-end VLM call latency
  - `matched_text_index` integer, nullable: Index into the request `texts` list when the answer is OCR-grounded.
  - `model` string, required: Model identifier returned by the provider
  - `prompt_tokens` integer: Prompt (input) tokens the model billed for this call

## Other responses

- `400`: Invalid input (bad image, unsupported model)
- `401`: Missing or invalid credential
- `402`: Insufficient balance
- `422`: Request validation failed
- `500`: Internal error (masked)
- `502`: The model provider failed

## Changes

- **2026-10-17** `2e42e4860799`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/argus-2/changes/api/v1/screenshots:locate/post.md)

---

[API](https://skmtc.dev/axilioai/apis/argus-2.md) - [All operations](https://skmtc.dev/axilioai/apis/argus-2/llms.txt) - [OpenAPI document](https://skmtc.dev/axilioai/apis/argus-2/revisions/62a8af730680?raw)