1. Query
  2. Metadata

Retrieve a set of objects that match a query. Sieve can be queried in way that’s similar to MongoDB. Currently, the following MongoDB operations are supported on all tags that exist within an object.


To see the schema of your project (which will determine how you use the above operations), you can call the /get_project_info endpoint. Attributes that change over time are encoded under the temporal attribute of an object while static attributes exist on the top-level.

Because return payload can be large, Sieve batches that payload into multiple pages which can be specificied using the next_start param. You will get the next start index in next_start everytime you make a query which you can include in your next query. If there are no more pages, next_start will be -1. The max batch size possible is 7500 objects, and the default batch size is 5000 objects. You also will get total_samples, which is the total amount of samples that satisfy your query.


project_namestringThe name of the project
next_start(optional) intThe amount of objects to skip in query (defaults to 0, used for paging)
YOUR_TAG(optional) object or stringOne of many tags in your schema. (you can specify as many of these as you want). These can be queried for in mongo format.



          curl 'https://api.sievedata.com/v1/query' \
    -X POST \
    -H "X-API-Key: YOUR_API_KEY" \ 
    -H "Content-Type: application/json" \
    -d '{
      "video_name": "video_1",
      "project_name": "amazing_project_1"
      "temporal.frame_number": {"$lte": 500, "$gte": 100},
      "class": {
        "$in": [

Sample Response

          {"description": "Successful. Returned 167 objects",
 "next_start": 167,
 "objects": [{"_id": "4af23cae-58ae-49d5-bbb3-2cd23ab69c54",
   "class": "car",
   "end_frame": 1248,
   "object_id": "4af23cae-58ae-49d5-bbb3-2cd23ab69c54",
   "project_name": "amazing_project_1",
   "start_frame": 1230,
   "temporal": [{"bbox": {"position": {"area": 1346.6105655468766,
       "height": 29.85799212551774,
       "width": 45.10050642005541,
       "x1": 448.0669623507817,
       "x2": 493.1674687708371,
       "y1": 309.0682736427327,
       "y2": 338.92626576825046},
      "speed": {"bottom_left": 4.315388630606474,
       "bottom_right": 30.15500296597246,
       "top_left": 10.622436250109503,
       "top_right": 31.67866437734206},
      "velocity": {"x1": 2.3676354637587047,
       "x2": -29.938392116710077,
       "y1": 10.355213865410631,
       "y2": -3.607891537161244}},
     "center": {"position": {"x": 470.6172155608094, "y": 323.9972697054916},
      "speed": 14.192189586332075,
     "count": 12,
     "frame_number": 342}],
   "video_name": "video_1"}],
 "query_latency": 0.810,
 "total_samples": 167}

Note: For projects with a field in the tag schema that contains has a “_type” of “text”, you can use the MongoDB Legacy text query engine to search for text information throughout the project. For more information, get started with a text enabled project like E-Sports or Live Social today!