Documentation Powered by ReDoc

Luna events API (v.4.0.1)

Download OpenAPI specification:Download

VisionLabs Luna Events API.

Introduction

This service is intended for searching events according to the specified filters and getting some statistics parameters of events. You can receive the following parameters:

1) event count, 2) average, max, min value numeric parameters.

Events can be grouped by the creation time. Grouping is possible in two ways: grouping by time intervals and the frequency grouping (by day of month).

The service store some fields in compressed state for query optimization and database size decrease.

Mapping ethnicities to ID:

Group name Group ID
african_american 1
indian 2
asian 3
caucasian 4

Mapping emotions to ID:

Group name Group ID
anger 1
disgust 2
fear 3
happiness 4
neutral 5
sadness 6
surprise 7

Mapping masks to ID:

Group name Group ID
missing 1
medical_mask 2
occluded 3

Mapping liveness to ID:

liveness value
spoof 0
real 1
unknown 2

OpenAPI specification is the only valid document providing up-to-date information about the service API.

The specification can be used:

  • By documentation generation tools to visualize the API.
  • By code generation tools.

All the documents and code generated using this specification can include inaccuracies and should be carefully checked.

OpenAPI specification can be received using the "/docs/spec" resource. The "Accept" header should be set to "application/x-yaml".

version

get version

Get version of service.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "Version": {
    }
}

events

check event

Check event existence by ID.

path Parameters
event_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Event ID.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

get event

Get event by ID. If target is not set, reply will contain all event fields.

path Parameters
event_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Event ID.

query Parameters
target
string
Enum: "account_id" "create_time" "end_time" "event_id" "handler_id" "external_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "body_detections" "body_basic_attributes" "upper_body" "accessories" "tags" "user_data" "location" "mask" "track_id"
Example: target=extract_result

Comma-separated list of event fields. If set, each event from result will contain only specified fields, otherwise, events with all fields will be returned.

account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "create_time": "2018-08-11T09:11:41.674Z",
  • "end_time": "2018-08-11T09:11:41.674Z",
  • "event_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "handler_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "account_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "external_id": "external id",
  • "source": "3rd Avenue",
  • "top_match": {
    },
  • "match_result": [
    ],
  • "face_detections": [
    ],
  • "body_detections": [
    ],
  • "body_basic_attributes": {
    },
  • "upper_body": {
    },
  • "accessories": {
    },
  • "face_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "attach_result": [
    ],
  • "gender": 0,
  • "age": 0,
  • "emotion": 1,
  • "mask": 1,
  • "ethnic_group": 1,
  • "liveness": 0,
  • "tags": [
    ],
  • "user_data": "",
  • "location": {
    },
  • "track_id": "useful_track_id_number_1"
}

patch event

Update event by ID.

path Parameters
event_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Event ID.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header.

Request Body schema:
application/json
application/json
application/msgpack
object (face_attributes_json)

Face attributes.

object (body_attributes_json)

Body attributes.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
{
  • "face_attributes": {
    },
  • "body_attributes": {
    }
}

Response samples

Content type
application/json
Example
bad_json
bad_json
bad_query_param
{}

get events

Get events that satisfy filters.

Default filters for events:

  • create_time__lt - current datetime

  • create_time__gte - current datetime minus month

    Default filters are not used if any of the following parameters are defined:

    • list of event IDs (event_ids)
    • lower event ID boundary (event_id__gte)
    • upper event ID boundary (event_id__lt)
    • lower create time boundary (create_time__gte)
    • upper create time boundary (create_time__lt)

The target parameter determines field that will be shown for each event. If target is not set, the response will contain all the fields, except the descriptor data.

To count events, use "get statistics on events" request.

query Parameters
target
string
Enum: "account_id" "create_time" "end_time" "event_id" "handler_id" "external_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "body_detections" "body_basic_attributes" "upper_body" "accessories" "tags" "user_data" "location" "mask" "track_id"
Example: target=extract_result

Comma-separated list of event fields. If set, each event from result will contain only specified fields, otherwise, events with all fields will be returned.

account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

create_time__gte
string <date-time>
Example: create_time__gte=2018-08-11T09:11:41.674Z

The lower create time including boundary.

create_time__lt
string <date-time>
Example: create_time__lt=2018-08-11T09:11:41.674Z

Upper bound for object create_time.

end_time__gte
string <date-time>
Example: end_time__gte=2018-08-11T09:11:41.674Z

The lower end time including boundary.

end_time__lt
string <date-time>
Example: end_time__lt=2018-08-11T09:11:41.674Z

Upper bound for object end_time.

sources
string
Example: sources=cam1,cam2

Comma-separated list of sources. Each event from result will contain one of the given sources.

top_matching_candidates_label
string
Example: top_matching_candidates_label=matching_label

Top matching candidates label. Each event from result will contain the given label.

top_similar_object_ids
Array of strings <uuid> (uuid)
Example: top_similar_object_ids=557d54ec-29ad-4f3c-93b4-c9092ef12515

Comma-separated list of top similar object IDs. Each event from result will contain one of the given top similar object IDs.

top_similar_external_ids
Array of strings (external_id)
Example: top_similar_external_ids=external id

Comma-separated list of top similar external IDs. Each event from result will contain one of the given top similar external IDs.

top_similar_object_similarity__gte
number
Example: top_similar_object_similarity__gte=0.5

Top similar object similarity lower included bound.

top_similar_object_similarity__lt
number
Example: top_similar_object_similarity__lt=0.5

Top similar object similarity upper excluded bound.

age__lt
integer [ 0 .. 100 ]
Example: age__lt=50

Age upper excluded bound.

age__gte
integer [ 0 .. 100 ]
Example: age__gte=50

Age lower included bound.

gender
integer
Enum: 0 1
Example: gender=1

Gender. 1 - male, 0 - female.

emotions
string <list of integer (1, 2, 3, 4, 5, 6, 7)>
Example: emotions=1,2,3

Comma-separated list of predominant emotions. Each event from result will contain one of the given emotions.

emotions value
anger 1
disgust 2
fear 3
happiness 4
neutral 5
sadness 6
surprise 7
masks
string <list of integer (1, 2, 3)>
Example: masks=1,2,3

Comma-separated list of predominant masks. Each event from result will contain one of the given mask state.

mask value
missing 1
medical_mask 2
occluded 3
ethnic_groups
string <list of integer (1, 2, 3, 4)>
Example: ethnic_groups=1,2

Comma-separated list of dominant ethnic group. Each event from result will contain one of the given ethnic groups.

ethnicity value
African american 1
Indian 2
Asian 3
Caucasian 4
liveness
string <list of integer (0, 1 ,2)>
Example: liveness=1,2

Comma-separated list of dominant liveness. Each event from result will contain one of the given liveness.

liveness value
spoof 0
real 1
unknown 2
apparent_gender
integer
Enum: 0 1 2
Example: apparent_gender=1

Comma-separated list of apparent gender: 0 - female, 1 - male, 2 - undefined. Each event from result will contain one of the given states.

apparent_age__gte
integer [ 0 .. 100 ]
Example: apparent_age__gte=50

Apparent age lower included bound.

apparent_age__lt
integer [ 0 .. 100 ]
Example: apparent_age__lt=50

Apparent age upper excluded bound.

headwear_states
integer
Enum: 0 1 2
Example: headwear_states=1

Comma-separated list of headwear states: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.

sleeve_lengths
string
Enum: "short" "long" "undefined"
Example: sleeve_lengths=short

Comma-separated list of sleeve length states. Each event from result will contain one of the given states.

upper_clothing_colors
string
Enum: "black" "blue" "green" "gray" "orange" "purple" "red" "white" "yellow" "pink" "brown" "beige" "khaki" "multicolored" "undefined"
Example: upper_clothing_colors=black,white

Comma-separated list of upper clothing colors. Each event from result will contain at least one of the given clothing colors.

backpack_states
integer
Enum: 0 1 2
Example: backpack_states=1

Comma-separated list of backpack states: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.

face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated face IDs.

event_ids
string <list of uuid.>
Example: event_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated event IDs.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Lower including event ID boundary.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc38

Upper excluding event ID boundary.

handler_ids
string <list of uuid.>
Example: handler_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated handler IDs.

external_ids
string <list of strings.>
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated external IDs.

user_data
string
Example: user_data=user_data

Find all objects with user_data that is similar to this parameter.

tags
Array of strings (tag) >= 0 items
Example: tags=tag_1,tag_2

Comma-separated list of tags. Each event from result will contain all of the given tags.

cities
string
Example: cities=moscow,New-York

Comma-separated list of cities. Each event from result will contain one of the given cities in location.

areas
string
Example: areas=CAO,central park

Comma-separated list of areas. Each event from result will contain one of the given areas in location.

districts
string
Example: districts=mitino,central park

Comma-separated list of districts. Each event from result will contain one of the given districts in location.

streets
string
Example: streets=arbat,schepkina

Comma-separated list of streets. Each event from result will contain one of the given streets in location.

house_numbers
string
Example: house_numbers=1,1/2str3

Comma-separated list of house numbers. Each event from result will contain one of the given house numbers in location.

origin_longitude
number (longitude) [ -180 .. 180 ]
Example: origin_longitude=36.616

Longitude origin in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

origin_latitude
number (latitude) [ -90 .. 90 ]
Example: origin_latitude=55.752

Latitude origin in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

longitude_delta
number [ 0 .. 90 ]
Default: 0.01
Example: longitude_delta=0.01

Longitude delta in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set. If both origin_longitude and origin_latitude are set and longitude_delta is not set - default is applied. WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected. Box edges more than 180 degrees long are not allowed. Boundaries of valid range are exclusive. NOTE: highly recommended for citywide use only.

latitude_delta
number [ 0 .. 90 ]
Default: 0.01
Example: latitude_delta=0.01

Latitude delta in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set. If both origin_longitude and origin_latitude are set and latitude_delta is not set - default is applied. WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected. Box edges more than 180 degrees long are not allowed. Boundaries of valid range are exclusive. NOTE: highly recommended for citywide use only.

track_ids
string <list of track ids>
Example: track_ids=track_id1,track_id_2

List of comma-separated track IDs.

order
string
Enum: "asc" "desc"

The sort order.

By default, the results will be sorted by event creation time. If "desc" is set, the newest events will be shown first. If "asc" is set, the oldest events will be shown first.

But if some event ID range filters specified (event_id__gte or event_id__lt), the results will be sorted by event ID.

page
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 1000 ]
Default: 10

Number of items on page.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

create new events

Creates new events.

query Parameters
wait_events_saving
integer (int01)
Default: 0
Enum: 0 1

Whether to wait for events saving.

If "0" is specified, the 202 status code will be expected in response to a successful request. This status code is returned after events are validated and added to the buffer. The system does not wait until the events are saved to the database. The events will be stored in the database after the response is sent.

If "1" is specified, the 204 status code will be expected in response to a successful request. This status code is returned only after events are stored in the database.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Enum: "application/json" "application/msgpack"

The response content type header.

Request Body schema:
application/json
application/json
application/msgpack
Array ()
account_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

account id.

create_time
required
string <date-time>

Event creation time.

end_time
string <date-time>

Event end time, if it was not set, the system will set it by the time of creation.

event_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Event ID.

handler_id
required
string <uuid> ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

ID of the handler, which gave birth to the event.

external_id
string <= 36 characters Nullable ^[^\x00]*$
Default: ""

user-defined external id for face

user_data
string <= 128 characters Nullable ^[^\x00]*$

user data.

source
string Nullable ^[^\x00]*$

Additional information that user provides with event.

track_id
string Nullable ^[a-zA-Z0-9_\-]{1,36}$

Event track ID.

tags
Array of strings Nullable

Tag array.

object Nullable

Face object.

Array of match_candidates_new_event_faces (object) or match_candidates_new_event_events (object) (match_candidates_new_event) Nullable

Matches list.

Array of objects

Detection list.

object (location)

Information about a place where event is incidented.

object

Aggregated estimations.

object (face_attributes_json)

Face attributes.

object (body_attributes_json)

Body attributes.

Responses

Request samples

Content type
application/json
application/json
application/msgpack
[
  • {
    }
]

Response samples

Content type
application/json
{}

delete events

Delete oldest 10000 events that satisfy filters.

query Parameters
target
Array of strings
Default: ["face_samples","body_samples","image_origins"]
Items Enum: "face_samples" "body_samples" "image_origins"
Example: target=image_origins

Comma-separated list of event deletion info attributes. If set, each item from the result will contain only specified attributes in addition to the event ID, otherwise, all the deletion info attributes will be returned. If empty value set, each item from the result will contain only event ID.

account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

handler_id
string <uuid.>
Example: handler_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Handler ID.

create_time__gte
string <date-time>
Example: create_time__gte=2018-08-11T09:11:41.674Z

The lower create time including boundary.

create_time__lt
string <date-time>
Example: create_time__lt=2018-08-11T09:11:41.674Z

Upper bound for object create_time.

insert_time__gte
string <date-time>
Example: insert_time__gte=2018-08-11T09:11:41.674Z

The lower insert time including boundary.

insert_time__lt
string <date-time>
Example: insert_time__lt=2018-08-11T09:11:41.674Z

The upper insert time excluding boundary.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

administration

get events with missing attributes

Get events with samples and with missing attributes that satisfy filters.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

kind
required
string
Enum: "basic_attributes" "face_descriptor" "body_descriptor"
Example: kind=basic_attributes

Kind of missing attributes to look for.

Only 1 value at time is supported because the response doesn't contain information required to distinguish kinds of the events.

insert_time__gte
string <date-time>
Example: insert_time__gte=2018-08-11T09:11:41.674Z

The lower insert time including boundary.

insert_time__lt
string <date-time>
Example: insert_time__lt=2018-08-11T09:11:41.674Z

The upper insert time excluding boundary.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Lower including event ID boundary.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc38

Upper excluding event ID boundary.

handler_id
string <uuid.>
Example: handler_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Handler ID.

missing_version
integer
Example: missing_version=56

Event descriptor version. By default used the platform default descriptor version.

page
integer >= 1
Default: 1

Page number.

page_size
integer [ 1 .. 1000 ]
Default: 10

Number of items on page.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

get count of events with missing attributes

Get count of events with samples and with missing attributes that satisfy filters.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

kind
required
string
Enum: "basic_attributes" "face_descriptor" "body_descriptor"
Example: kind=basic_attributes

Kind of missing attributes to look for.

Only 1 value at time is supported because the response doesn't contain information required to distinguish kinds of the events.

insert_time__gte
string <date-time>
Example: insert_time__gte=2018-08-11T09:11:41.674Z

The lower insert time including boundary.

insert_time__lt
string <date-time>
Example: insert_time__lt=2018-08-11T09:11:41.674Z

The upper insert time excluding boundary.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Lower including event ID boundary.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc38

Upper excluding event ID boundary.

handler_id
string <uuid.>
Example: handler_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Handler ID.

missing_version
integer
Example: missing_version=56

Event descriptor version. By default used the platform default descriptor version.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "events_count": 55
}

delete events descriptors

Delete 10000 event descriptors that satisfy filters.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Lower including event ID boundary.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc38

Upper excluding event ID boundary.

version
required
integer [ 0 .. 1000 ]
Example: version=56

Event descriptor version.

descriptor_type
required
string
Enum: "face" "body"
Example: descriptor_type=face

The type of the event's descriptor.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "event_ids": [
    ]
}

event descriptor

get event descriptor

Get event descriptor that corresponds to the specified parameters.

path Parameters
event_id
required
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: 557d54ec-29ad-4f3c-93b4-c9092ef12515

Event ID.

query Parameters
account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

descriptor_version
integer [ 0 .. 110 ]
Example: descriptor_version=56

Event descriptor version. By default used the platform default descriptor version.

descriptor_type
string
Enum: "face" "body"
Example: descriptor_type=face

The type of the event's descriptor.

header Parameters
Accept
string
Example: application/x-sdk-descriptor

Content type which is acceptable for the response. If 'application/x-sdk-descriptor' is specified, the binary descriptor will be returned in the response body, otherwise 'application/json' content type will be applied.

Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
application/json
application/x-sdk-descriptor
{
  • "descriptor": "string",
  • "descriptor_version": 52
}

events stats

get statistics on events

Get event statistics by target(s) with applied filters.

Event fields and/or functions (count, min, etc.) can be set as targets for aggregation of events.

Grouping by frequency or grouping by time intervals is available.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Content-Type
string
Value: "application/json"

Content type is application/json.

Request Body schema: application/json
Array of objects (targets) non-empty
Default: [{"column":"event_id","aggregator":"count"}]

Fields and functions to aggregate.

Allowed usage of aggregators is:

Column Aggregator
count max min avg group_by
event_id + - - - +
external_id + - - - +
handler_id + - - - +
source + - - - +
top_similar_object_id + - - - +
top_similar_external_id + - - - +
top_matching_candidates_label + - - - +
create_time + + + - -
end_time + + + - -
top_similar_object_similarity + + + + -
face_id + - - - +
gender + + + + +
age + + + + +
emotion + + + + +
mask + + + + +
ethnic_group + + + + +
liveness + + + + +
user_data + - - - +
tags + + + - -
city + - - - +
area + - - - +
district + - - - +
street + - - - +
house_number + - - - +
geo_position + - - - -
track_id + - - - +
Array of objects (filters) >= 0 items

Set of filters for sample restriction.

Allowed usage of filters is:

Filter Operator
like, nlike in, nin eq, neq gt, gte, lt, lte covered
tags + - - - -
source - + + - -
user_data - + + - -
account_id - + + + -
event_id - + + + -
external_id - + + + -
handler_id - + + + -
top_similar_object_id - + + + -
top_similar_external_id - + + + -
top_matching_candidates_label - + + - -
top_similar_object_similarity - - - + -
face_id - + + + -
gender - + + + -
age - + + + -
emotion - + + + -
mask - + + + -
ethnic_group - + + + -
liveness - + + + -
city - + + - -
area - + + - -
district - + + - -
street - + + - -
house_number - + + - -
geo_position - - - - +
track_id - + + - -

Warning: must be at least one aggregator different with 'group_by' in request

Array of objects (periods) >= 0 items

It is possible to set start and end of period.

group_by
string (group_by)

Event for grouping by creation time.

Grouping is possible in two ways

1) Grouping by time intervals - number and dimension

The parameter value Description
1m one minute
2h two hours
7d seven days
5w five weeks
3M three months
10y ten years

2) The frequency grouping - one of the following

The parameter value Description
monthOfYear by month of year
weekOfYear by week of year
dayOfYear by day of year
dayOfMonth by day of month
dayOfWeek by day of week
hourOfDay by hours of day
minuteOfHour by minutes of hour

Responses

Request samples

Content type
application/json
{
  • "targets": [
    ],
  • "filters": [
    ],
  • "period": [
    ],
  • "group_by": "dayOfWeek"
}

Response samples

Content type
application/json
{
  • "fields": [
    ],
  • "stats": [
    ]
}

events match

match events

Match events that satisfy filters.

Default filters for match events:

  • create_time__lt - current datetime

  • create_time__gte - current datetime minus month

    Default filters are not used if any of the following parameters are defined:

    • list of event IDs (event_ids)
    • lower event ID boundary (event_id__gte)
    • upper event ID boundary (event_id__lt)
    • lower create time boundary (create_time__gte)
    • upper create time boundary (create_time__lt)

If target is not set, the response will contain events with "event_id" and "similarity" fields only.

To count events, use "get statistics on events" request.

query Parameters
target
string
Enum: "account_id" "create_time" "end_time" "event_id" "handler_id" "external_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "body_detections" "body_basic_attributes" "upper_body" "accessories" "tags" "user_data" "location" "mask" "track_id" "similarity"
Example: target=extract_result,similarity

Comma-separated list of event fields. If set, each event from result will contain only specified fields, otherwise, events with the "event_id" and "similarity" fields will be returned.

account_id
string <uuid> (uuid) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...
Example: account_id=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Account ID.

create_time__gte
string <date-time>
Example: create_time__gte=2018-08-11T09:11:41.674Z

The lower create time including boundary.

create_time__lt
string <date-time>
Example: create_time__lt=2018-08-11T09:11:41.674Z

Upper bound for object create_time.

end_time__gte
string <date-time>
Example: end_time__gte=2018-08-11T09:11:41.674Z

The lower end time including boundary.

end_time__lt
string <date-time>
Example: end_time__lt=2018-08-11T09:11:41.674Z

Upper bound for object end_time.

sources
string
Example: sources=cam1,cam2

Comma-separated list of sources. Each event from result will contain one of the given sources.

top_matching_candidates_label
string
Example: top_matching_candidates_label=matching_label

Top matching candidates label. Each event from result will contain the given label.

top_similar_object_ids
Array of strings <uuid> (uuid)
Example: top_similar_object_ids=557d54ec-29ad-4f3c-93b4-c9092ef12515

Comma-separated list of top similar object IDs. Each event from result will contain one of the given top similar object IDs.

top_similar_external_ids
Array of strings (external_id)
Example: top_similar_external_ids=external id

Comma-separated list of top similar external IDs. Each event from result will contain one of the given top similar external IDs.

top_similar_object_similarity__gte
number
Example: top_similar_object_similarity__gte=0.5

Top similar object similarity lower included bound.

top_similar_object_similarity__lt
number
Example: top_similar_object_similarity__lt=0.5

Top similar object similarity upper excluded bound.

age__lt
integer [ 0 .. 100 ]
Example: age__lt=50

Age upper excluded bound.

age__gte
integer [ 0 .. 100 ]
Example: age__gte=50

Age lower included bound.

gender
integer
Enum: 0 1
Example: gender=1

Gender. 1 - male, 0 - female.

emotions
string <list of integer (1, 2, 3, 4, 5, 6, 7)>
Example: emotions=1,2,3

Comma-separated list of predominant emotions. Each event from result will contain one of the given emotions.

emotions value
anger 1
disgust 2
fear 3
happiness 4
neutral 5
sadness 6
surprise 7
masks
string <list of integer (1, 2, 3)>
Example: masks=1,2,3

Comma-separated list of predominant masks. Each event from result will contain one of the given mask state.

mask value
missing 1
medical_mask 2
occluded 3
ethnic_groups
string <list of integer (1, 2, 3, 4)>
Example: ethnic_groups=1,2

Comma-separated list of dominant ethnic group. Each event from result will contain one of the given ethnic groups.

ethnicity value
African american 1
Indian 2
Asian 3
Caucasian 4
liveness
string <list of integer (0, 1 ,2)>
Example: liveness=1,2

Comma-separated list of dominant liveness. Each event from result will contain one of the given liveness.

liveness value
spoof 0
real 1
unknown 2
apparent_gender
integer
Enum: 0 1 2
Example: apparent_gender=1

Comma-separated list of apparent gender: 0 - female, 1 - male, 2 - undefined. Each event from result will contain one of the given states.

apparent_age__gte
integer [ 0 .. 100 ]
Example: apparent_age__gte=50

Apparent age lower included bound.

apparent_age__lt
integer [ 0 .. 100 ]
Example: apparent_age__lt=50

Apparent age upper excluded bound.

headwear_states
integer
Enum: 0 1 2
Example: headwear_states=1

Comma-separated list of headwear states: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.

sleeve_lengths
string
Enum: "short" "long" "undefined"
Example: sleeve_lengths=short

Comma-separated list of sleeve length states. Each event from result will contain one of the given states.

upper_clothing_colors
string
Enum: "black" "blue" "green" "gray" "orange" "purple" "red" "white" "yellow" "pink" "brown" "beige" "khaki" "multicolored" "undefined"
Example: upper_clothing_colors=black,white

Comma-separated list of upper clothing colors. Each event from result will contain at least one of the given clothing colors.

backpack_states
integer
Enum: 0 1 2
Example: backpack_states=1

Comma-separated list of backpack states: 0 - absent, 1 - present, 2 - undefined. Each event from result will contain one of the given states.

face_ids
string <list of uuid>
Example: face_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated face IDs.

event_ids
string <list of uuid.>
Example: event_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated event IDs.

event_id__gte
string <uuid.>
Example: event_id__gte=8950722f-3fd4-4223-b48f-03f95f0e8dfb

Lower including event ID boundary.

event_id__lt
string <uuid.>
Example: event_id__lt=346a5645-ec89-4806-820a-dbcb6e0dc38

Upper excluding event ID boundary.

handler_ids
string <list of uuid.>
Example: handler_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated handler IDs.

external_ids
string <list of strings.>
Example: external_ids=8950722f-3fd4-4223-b48f-03f95f0e8dfb,346a5645-ec89-4806-820a-dbcb6e0dc38

List of comma-separated external IDs.

user_data
string
Example: user_data=user_data

Find all objects with user_data that is similar to this parameter.

tags
Array of strings (tag) >= 0 items
Example: tags=tag_1,tag_2

Comma-separated list of tags. Each event from result will contain all of the given tags.

cities
string
Example: cities=moscow,New-York

Comma-separated list of cities. Each event from result will contain one of the given cities in location.

areas
string
Example: areas=CAO,central park

Comma-separated list of areas. Each event from result will contain one of the given areas in location.

districts
string
Example: districts=mitino,central park

Comma-separated list of districts. Each event from result will contain one of the given districts in location.

streets
string
Example: streets=arbat,schepkina

Comma-separated list of streets. Each event from result will contain one of the given streets in location.

house_numbers
string
Example: house_numbers=1,1/2str3

Comma-separated list of house numbers. Each event from result will contain one of the given house numbers in location.

origin_longitude
number (longitude) [ -180 .. 180 ]
Example: origin_longitude=36.616

Longitude origin in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

origin_latitude
number (latitude) [ -90 .. 90 ]
Example: origin_latitude=55.752

Latitude origin in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set.

longitude_delta
number [ 0 .. 90 ]
Default: 0.01
Example: longitude_delta=0.01

Longitude delta in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set. If both origin_longitude and origin_latitude are set and longitude_delta is not set - default is applied. WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected. Box edges more than 180 degrees long are not allowed. Boundaries of valid range are exclusive. NOTE: highly recommended for citywide use only.

latitude_delta
number [ 0 .. 90 ]
Default: 0.01
Example: latitude_delta=0.01

Latitude delta in degrees, a part of composite geo position filter. Geo position filter is a bounding box specified by coordinates of its center (origin) and some delta. Geo position filter is considered as properly specified if both origin_longitude and origin_latitude are set, and considered as properly empty if neither of origin_longitude, origin_latitude, longitude_delta, latitude_delta is set. If both origin_longitude and origin_latitude are set and latitude_delta is not set - default is applied. WARNING: boxes with a vertex or border on the International Date Line (IDL) or the North or South pole are not fully supported due to features of database spatial index - filter result may be unexpected. Box edges more than 180 degrees long are not allowed. Boundaries of valid range are exclusive. NOTE: highly recommended for citywide use only.

track_ids
string <list of track ids>
Example: track_ids=track_id1,track_id_2

List of comma-separated track IDs.

order
string
Enum: "asc" "desc"

The sort order. If "desc" is set, the most similar events will be shown first. If "asc" is set, the least similar events will be shown first.

threshold
number [ 0 .. 1 ]
Default: 0

Event similarity threshold in a match response - events with a similarity lower than this parameter will not be returned.

limit
integer [ 1 .. 1000000 ]
Default: 5

Event limit in a match response.

descriptor_type
string
Enum: "face" "body"
Example: descriptor_type=face

The type of the event's descriptor.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Request Body schema:
application/json
application/json
application/x-sdk-descriptor
descriptor
required
string <base64>

Raw descriptor bytes encoded in base64.

descriptor_version
required
integer

Descriptor version.

Responses

Request samples

Content type
application/json
application/json
application/x-sdk-descriptor
{
  • "descriptor": "string",
  • "descriptor_version": 52
}

Response samples

Content type
application/json
{
  • "events": [
    ]
}

documents

get openapi documentation

Get service OpenApi documentation. If Accept request header is of type application/x-yaml, returns documentation in yaml format or returns html documentation, if Accept-Type is text/html.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Accept
required
string (accept_docs_handler)
Enum: "application/x-yaml" "text/html"

Acceptable type of receiving data.

Responses

Response samples

Content type
application/json
{}

get development manual

Get sphinx documentation - Development Manual. After the request you will be redirected to the page /docs/dev/index.html.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{}

config

get service configuration

Get service configuration. Passwords and tokens will be hidden in the response.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Accept
string
Enum: "application/json" "text/plain"

Acceptable type of receiving data

Responses

Response samples

Content type
application/json
application/json
text/plain
{
  • "INFLUX_MONITORING": {
    }
}

health

get health

Get health of service.

header Parameters
Luna-Request-Id
string <timestamp,uuid> ^[0-9]{10},[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4...
Example: 1536751345,8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

External request ID. Helps to uniquely identify messages that correspond to particular requests, in system logs. If it was not set, system will set it in default format ("timestamp,UUID"). It will be returned with response.

Responses

Response samples

Content type
application/json
{
  • "execution_time": 0.123
}