---
title: "Locate Element"
method: POST
path: "/api/v1/elements:locate"
tags: ["Elements"]
---

# Locate Element

`POST /api/v1/elements:locate`

## Request

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

Find the element a query describes among the given UI elements.

Answers with one of the request's element ids, or not found; never a point.

## Request body

- ElementLocateRequest: Argus POST /elements:locate request. Grounds a natural-language query in a list of UI elements: the model picks one of `elements`. The screenshot is optional context; the answer is always an element, never a point.
  - `elements` Element[], required: Candidate elements
    - `bounds` ElementBounds: Pixel box of an element, top-left origin. In the screenshot's pixel space when the request carries one, else in the device's screen space. An element scrolled partly off-screen has a negative origin; a collapsed element may have zero width or height.
      - `height` integer, required: Height in pixels
      - `width` integer, required: Width in pixels
      - `x` integer, required: Left edge in pixels; negative when the element starts off-screen
      - `y` integer, required: Top edge in pixels; negative when the element starts off-screen
    - `id` string, required: Caller's id for the element, unique in the request
    - `name` string: Accessible name; empty when the element has none
    - `platform` object, nullable: Native attributes keyed by platform, passed through to the model (at most 4096 bytes as JSON)
    - `role` string, required: Role, e.g. 'button', 'textbox'
    - `value` string, nullable: Current value (a text field's contents), when any
  - `image` string, nullable: Optional base64 screenshot (PNG or JPEG) the element bounds are in
  - `model` string, nullable: VLM model to use; must be one of the models from GET /models. Omit to use the server's configured default.
  - `query` string, required: Natural-language target description

## Response `200`

Successful Response

- ElementLocateResponse: Argus POST /elements:locate response. `element_id` is one of the request's element ids when `found`, else null. It names the element rather than indexing the list, so the answer does not depend on element order. The billing fields match screenshot locate.
  - `cache_read_tokens` integer: Prompt tokens read from cache
  - `cache_write_tokens` integer: Prompt tokens written to cache
  - `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
  - `element_id` string, nullable: The chosen element's id; null when not found
  - `found` boolean, required: Whether the model picked an element
  - `latency_ms` integer, required: End-to-end VLM call latency
  - `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-11-01** `0d40f346c063`: 2 info
  - added the optional property `cache_read_tokens` to the response with the `200` status
  - added the optional property `cache_write_tokens` to the response with the `200` status
- **2026-10-17** `35d5ebb1d52b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/axilioai/apis/argus/changes/api/v1/elements: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.dev/axilioai/apis/argus/revisions/0d40f346c063?raw)