> ## Documentation Index
> Fetch the complete documentation index at: https://docs.axilio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Elements: locate

> 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.

Choose the UI element that a natural-language query describes from a list of
elements you already have. You send the candidates, and Argus answers with one
of your element `id` values as `element_id`, or `found: false`. It never
answers with a point, so you act on the element itself.

## Why elements and screenshots are separate operations

Screenshot grounding and element grounding take different inputs and give
different answers. A screenshot locate reads pixels and returns a box. An
element locate reads structured elements and returns an element ID. Keeping
them as separate operations gives each one a request and response that fit it
exactly.

The element operation doesn't care where your elements came from. A browser
DOM, the results of [Screenshots: detect](/api-reference/argus/screenshots-detect),
or any other UI tree all map onto the same shape: an `id`, a `role`, a `name`,
an optional `value`, optional pixel `bounds`, and an optional `platform` object
of native attributes, which Argus passes to the model as given.

## Request

* **`query`** describes the target, such as `"the Sign in button"`. Up to 2,000
  characters.
* **`elements`** holds 1 to 2,000 candidates. Each `id` must be unique in the
  request; a duplicate is a validation error. An `id` is at most 256
  characters, a `role` at most 64, a `name` or `value` at most 1,024, and a
  `platform` object at most 4 KiB as JSON.
* **`image`** is an optional base64 PNG or JPEG screenshot. When you send one,
  give `bounds` in that screenshot's pixel space.
* **`model`** is an optional vision-language model from
  [Models: list](/api-reference/argus/list-models). Omit it to use the default.

```json theme={null}
{
  "query": "the Sign in button",
  "elements": [
    {"id": "12", "role": "textbox", "name": "Email", "value": ""},
    {"id": "13", "role": "textbox", "name": "Password"},
    {
      "id": "14",
      "role": "button",
      "name": "Sign in",
      "bounds": {"x": 96, "y": 1480, "width": 888, "height": 144}
    }
  ]
}
```

## Response

`found` tells you whether the model chose an element. When it did,
`element_id` is one of the IDs you sent. Argus checks the answer against your
request, so an ID you didn't send comes back as not found rather than as a
guess. `confidence` is the model's own estimate from 0 to 1.

```json theme={null}
{
  "found": true,
  "element_id": "14",
  "confidence": 0.97,
  "model": "anthropic/claude-haiku-4.5",
  "cost_microdollars": 412,
  "prompt_tokens": 1210,
  "completion_tokens": 18,
  "latency_ms": 640
}
```

## Billing

Element locate is billed per token on the model it ran, the same way as
[Screenshots: locate](/api-reference/argus/screenshots-locate). Usage rows
label it with the endpoint `element_locate`. See [Usage](/usage/overview#inference-usage).

Errors use the [problem details](/reference/errors#problem-details) shape.


## OpenAPI

````yaml api-reference/openapi-argus.json POST /api/v1/elements:locate
openapi: 3.1.0
info:
  title: Argus
  version: 2.0.0
servers:
  - url: https://argus.axilio.ai
    description: Production
security: []
tags:
  - name: Elements
  - name: Models
  - name: Screenshots
paths:
  /api/v1/elements:locate:
    post:
      tags:
        - Elements
      summary: Locate Element
      description: >-
        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.
      operationId: elements_locate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElementLocateRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElementLocateResponse'
          description: Successful Response
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Invalid input (bad image, unsupported model)
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Missing or invalid credential
        '402':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Insufficient balance
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Request validation failed
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: Internal error (masked)
        '502':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: The model provider failed
      security:
        - AxilioApiKey: []
components:
  schemas:
    ElementLocateRequest:
      description: >-
        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.
      properties:
        elements:
          description: Candidate elements
          items:
            $ref: '#/components/schemas/Element'
          maxItems: 2000
          minItems: 1
          title: Elements
          type: array
        image:
          anyOf:
            - maxLength: 16777216
              type: string
            - type: 'null'
          description: Optional base64 screenshot (PNG or JPEG) the element bounds are in
          title: Image
        model:
          anyOf:
            - minLength: 1
              type: string
            - type: 'null'
          description: >-
            VLM model to use; must be one of the models from GET /models. Omit
            to use the server's configured default.
          title: Model
        query:
          description: Natural-language target description
          maxLength: 2000
          minLength: 1
          title: Query
          type: string
      required:
        - query
        - elements
      title: ElementLocateRequest
      type: object
    ElementLocateResponse:
      description: >-
        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.
      properties:
        completion_tokens:
          default: 0
          description: Completion (output) tokens the model billed for this call
          minimum: 0
          title: Completion Tokens
          type: integer
        confidence:
          description: Model self-reported confidence
          maximum: 1
          minimum: 0
          title: Confidence
          type: number
        cost_microdollars:
          description: Provider-reported cost in microdollars
          minimum: 0
          title: Cost Microdollars
          type: integer
        element_id:
          anyOf:
            - type: string
            - type: 'null'
          description: The chosen element's id; null when not found
          title: Element Id
        found:
          description: Whether the model picked an element
          title: Found
          type: boolean
        latency_ms:
          description: End-to-end VLM call latency
          minimum: 0
          title: Latency Ms
          type: integer
        model:
          description: Model identifier returned by the provider
          title: Model
          type: string
        prompt_tokens:
          default: 0
          description: Prompt (input) tokens the model billed for this call
          minimum: 0
          title: Prompt Tokens
          type: integer
      required:
        - found
        - confidence
        - model
        - cost_microdollars
        - latency_ms
      title: ElementLocateResponse
      type: object
    Problem:
      description: RFC 9457 problem details, as argus (and the backend) answer every error.
      properties:
        code:
          description: Stable machine-readable category, e.g. validation, not_found
          title: Code
          type: string
        detail:
          description: Human-readable explanation; masked for internal errors
          title: Detail
          type: string
        errors:
          anyOf:
            - items:
                additionalProperties:
                  type: string
                type: object
              type: array
            - type: 'null'
          default: null
          description: Per-field messages on a request validation problem
          title: Errors
        status:
          description: The HTTP status code
          title: Status
          type: integer
        title:
          description: The status's reason phrase
          title: Title
          type: string
        type:
          default: about:blank
          description: Always about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - detail
        - code
      title: Problem
      type: object
    Element:
      description: >-
        One UI element offered as a candidate target.


        Source-neutral: an element from a DOM, a detector's output or any other

        UI tree maps onto it. `platform` carries native attributes the caller
        wants the model

        to see; it is opaque to argus and passed through to the model as given.
      properties:
        bounds:
          anyOf:
            - $ref: '#/components/schemas/ElementBounds'
            - type: 'null'
          description: Where the element is on screen
        id:
          description: Caller's id for the element, unique in the request
          maxLength: 256
          minLength: 1
          title: Id
          type: string
        name:
          default: ''
          description: The element's name or label; empty when the element has none
          maxLength: 1024
          title: Name
          type: string
        platform:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Native attributes keyed by platform, passed through to the model (at
            most 4096 bytes as JSON)
          title: Platform
        role:
          description: Role, e.g. 'button', 'textbox'
          maxLength: 64
          title: Role
          type: string
        value:
          anyOf:
            - maxLength: 1024
              type: string
            - type: 'null'
          description: Current value (a text field's contents), when any
          title: Value
      required:
        - id
        - role
      title: Element
      type: object
    ElementBounds:
      description: >-
        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.
      properties:
        height:
          description: Height in pixels
          minimum: 0
          title: Height
          type: integer
        width:
          description: Width in pixels
          minimum: 0
          title: Width
          type: integer
        x:
          description: Left edge in pixels; negative when the element starts off-screen
          title: X
          type: integer
        'y':
          description: Top edge in pixels; negative when the element starts off-screen
          title: 'Y'
          type: integer
      required:
        - x
        - 'y'
        - width
        - height
      title: ElementBounds
      type: object
  securitySchemes:
    AxilioApiKey:
      description: Axilio API key (axl_*).
      in: header
      name: X-Axilio-Api-Key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.