---
title: "Run Locate"
method: POST
path: "/api/v1/vision/locate"
tags: ["Vision"]
---

# Run Locate

`POST /api/v1/vision/locate`

## Request body

- LocateRequest — Argus /vision/locate request. The caller pre-computes OCR via /vision/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 /vision/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 /vision/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

- `422` — Validation Error

## Changes

- **2026-07-03** `93466e1dd588` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/axilioai/apis/argus/changes/api/v1/vision/locate/post.md)

---

[API](https://skmtc.dev/axilioai/apis/argus.md) · [All operations](https://skmtc.dev/axilioai/apis/argus/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/axilioai/argus/revisions/9977e34fbd8e/schema)