# Object Tracking Query
### Object Tracking Query API
Send a single query frame to detect and localize one of your tracked objects. The request returns a 6-DoF pose for the object that is visible in the frame.
The request takes an `objectCode` (a single string or an **array of up to 10 codes**), which is what enables multi-object tracking in a single session.
#### Tracking multiple objects in one query
`objectCode` can be an array — pass **1 to 10** object codes in a single query when your application is set up to track several different objects but only one is expected to be in the camera frame at any moment.
This is useful when:
* Your scene contains a small set of known trackable objects (e.g. five different products on a shelf, or three machines in a maintenance bay) and you want MultiSet to figure out which one the user is currently looking at.
* You don't want to run separate per-object queries every frame and pick the best result client-side — let the cloud do the matching across the candidate objects in one round trip.
**How it works:** if you pass, say, 5 object codes, the cloud searches the query frame against the tracking maps for **all 5** candidates and detects whichever object is visible in the frame. If multiple candidates are in view, the system returns the best match.
{% hint style="warning" %}
**Only one tracking pose is returned per query.** Even when you send multiple object codes, the response contains the pose for the **single object** the system detected in that frame. The detected object is identified in the `objectCodes` field of the response (an array containing the matched code).
To track two or more objects **simultaneously** in the same frame, send separate queries — multi-object pose return in a single response is not currently supported.
{% endhint %}
{% hint style="info" %}
All object codes in a single query must belong to your account and be in `active` status. Unknown, inactive, or cross-account codes are rejected. Maximum 10 candidates per query.
{% endhint %}
#### Request body fields
| Field | Type | Required | Notes |
| ----------------- | -------------------------- | -------- | -------------------------------------------------------------------- |
| `queryImage` | file (multipart) | yes | Single RGB frame from the device camera. |
| `objectCode` | string \| string\[] (1–10) | yes | Object code(s) to match against. |
| `fx`, `fy` | number | yes | Camera focal length in pixels. |
| `px`, `py` | number | yes | Camera principal point in pixels. |
| `width`, `height` | number | yes | Query image resolution in pixels. |
| `isRightHanded` | boolean | no | Default `false` (LHS / Unity). Set `true` for RHS coordinate output. |
## ModelSet Query API
> Query a VPS object using an uploaded image and camera parameters. \
> Accepts objectCode to identify the target object,\
> and returns the query result from the external API.
```json
{"openapi":"3.0.0","info":{"title":"ModelSet Query API","version":"1.0.0"},"servers":[{"url":"https://api.multiset.ai/v1","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Standard Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""}},"schemas":{"VPSObjectQueryResult":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the query was successful"},"result":{"type":"object","description":"Contains the localization result if the query was successful.","properties":{"position":{"type":"object","properties":{"x":{"type":"number","format":"float","description":"X-coordinate of the object position"},"y":{"type":"number","format":"float","description":"Y-coordinate of the object position"},"z":{"type":"number","format":"float","description":"Z-coordinate of the object position"}}},"rotation":{"type":"object","properties":{"qx":{"type":"number","format":"float","description":"Quaternion X component"},"qy":{"type":"number","format":"float","description":"Quaternion Y component"},"qz":{"type":"number","format":"float","description":"Quaternion Z component"},"qw":{"type":"number","format":"float","description":"Quaternion W component"}}},"confidence":{"type":"number","format":"float","description":"Confidence score of the query result","minimum":0,"maximum":1}}},"message":{"type":"string","description":"A descriptive message about the outcome of the query."}},"required":["success","message"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A message detailing the error."}},"required":["error"]}}},"paths":{"/vps/object/query":{"post":{"summary":"ModelSet Query API","description":"Query a VPS object using an uploaded image and camera parameters. \nAccepts objectCode to identify the target object,\nand returns the query result from the external API.\n","tags":["Object"],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"objectCode":{"type":"string","description":"The code of the VPS object"},"fx":{"type":"string","description":"Camera intrinsic parameter fx (focal length x-axis)"},"fy":{"type":"string","description":"Camera intrinsic parameter fy (focal length y-axis)"},"px":{"type":"string","description":"Camera intrinsic parameter px (principal point x-coordinate)"},"py":{"type":"string","description":"Camera intrinsic parameter py (principal point y-coordinate)"},"isRightHanded":{"type":"string","enum":["true","false"],"description":"Specifies whether the coordinate system is right-handed. Because this is form-data, it's sent as a string (\"true\" or \"false\").\n"},"width":{"type":"string","description":"The width (in pixels) of the input image"},"height":{"type":"string","description":"The height (in pixels) of the input image"},"queryImage":{"type":"string","format":"binary","description":"The image file to query against the object"}},"required":["fx","fy","px","py","width","height","isRightHanded","queryImage","objectCode"]}}}},"responses":{"200":{"description":"Query successful","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VPSObjectQueryResult"}}}},"400":{"description":"Bad request - Invalid parameters or missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden - Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
#### Sample Response — pose found
When the cloud detects one of the candidate objects in the query frame:
```json
{
"poseFound": true,
"position": {
"x": 1.4085917235274734,
"y": 0.4753337271392171,
"z": 0.6372062117019925
},
"rotation": {
"x": -0.10826634872129595,
"y": 0.48317258532326446,
"z": 0.07714477353215363,
"w": 0.8653735230773266
},
"confidence": 0.46301103179753406,
"objectCodes": [
"OBJ_CL4JCEKIHWAJ"
]
}
```
* `position` / `rotation` — the detected object's 6-DoF pose in the camera coordinate frame (LHS / Unity by default; RHS when `isRightHanded=true`).
* `objectCodes` — array containing the **single matched object code**, even if multiple candidates were sent in the request. Use this field to tell which object was detected.
* `confidence` — match confidence in `[0, 1]`.
#### Sample Response — pose not found
When none of the candidate objects could be detected in the frame:
```json
{
"poseFound": false,
"errorCode": "001",
"errorMessage": "Pose not found"
}
```
This is the expected response when the user hasn't pointed the camera at any of the tracked objects yet, or when the view is too occluded / motion-blurred. Continue querying with new frames until `poseFound` is `true`.
### List Objects API
Returns the object codes available in your account — useful for building the candidate list you'll send to `/vps/object/query`.
## Get a paginated list of VPS objects
> Retrieves a paginated list of VPS objects. You can use query parameters \
> to filter or search objects by name, and control pagination settings.
```json
{"openapi":"3.0.0","info":{"title":"VPS Object List API","version":"1.0.0"},"servers":[{"url":"https://api.multiset.ai/v1","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Standard Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\""}},"schemas":{"VPSObjectListResult":{"type":"object","properties":{"data":{"type":"array","description":"Array of VPS objects for the current page","items":{"$ref":"#/components/schemas/VPSObject"}},"currentPage":{"type":"integer","description":"Current page number","minimum":1},"totalPages":{"type":"integer","description":"Total number of pages available","minimum":0},"totalCount":{"type":"integer","description":"Total number of objects across all pages","minimum":0}},"required":["data","currentPage","totalPages","totalCount"]},"VPSObject":{"type":"object","properties":{"_id":{"type":"string","description":"Unique identifier for the VPS object"},"objectName":{"type":"string","description":"Human-readable name of the object"},"trackingType":{"type":"string","description":"Type of tracking used for this object","enum":["side","top","front","all"]},"source":{"type":"object","description":"Information about the object's source and format","properties":{"provider":{"type":"string","description":"Source provider of the object","enum":["web","mobile","desktop","api"]},"fileType":{"type":"string","description":"File format of the 3D object","enum":["glb","obj","fbx","dae"]},"coordinateSystem":{"type":"string","description":"Coordinate system used by the object","enum":["RHS","LHS"]}},"required":["provider","fileType","coordinateSystem"]}},"required":["_id","objectName","trackingType","source"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A message detailing the error."}},"required":["error"]}}},"paths":{"/vps/object":{"get":{"summary":"Get a paginated list of VPS objects","description":"Retrieves a paginated list of VPS objects. You can use query parameters \nto filter or search objects by name, and control pagination settings.\n","tags":["Object"],"parameters":[{"in":"query","name":"page","schema":{"type":"integer","minimum":1,"default":1},"required":false,"description":"The page number for pagination (starting from 1)"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":10},"required":false,"description":"Number of records per page (maximum 100)"},{"in":"query","name":"query","schema":{"type":"string","maxLength":255},"required":false,"description":"Filter or search text for partial match on object names"}],"responses":{"200":{"description":"A paginated list of VPS objects retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VPSObjectListResult"}}}},"400":{"description":"Bad request - Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized - Missing or invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.multiset.ai/basics/rest-api-docs/object-query.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.