API docs by Redocly

Luna events API (v.4.12.0)

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" "stream_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "deepfake" "body_detections" "body_basic_attributes" "upper_body" "lower_body" "accessories" "tags" "user_data" "location" "mask" "track_id" "meta"
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",
  • "stream_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "top_match": {
    },
  • "match_result": [
    ],
  • "face_detections": [
    ],
  • "body_detections": [
    ],
  • "body_basic_attributes": {
    },
  • "upper_body": {
    },
  • "lower_body": {
    },
  • "accessories": {
    },
  • "face_id": "b668c4a5-2191-476e-a261-3b4f9ce2e25e",
  • "attach_result": [
    ],
  • "gender": 0,
  • "age": 100,
  • "emotion": 1,
  • "mask": 1,
  • "ethnic_group": 1,
  • "liveness": 0,
  • "deepfake": 0,
  • "tags": [
    ],
  • "user_data": "",
  • "location": {
    },
  • "track_id": "useful_track_id_number_1",
  • "meta": { }
}

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:
object (face_attributes_json)

Face attributes.

object (body_attributes_json)

Body attributes.

Responses

Request samples

Content type
{
  • "face_attributes": {
    },
  • "body_attributes": {
    }
}

Response samples

Content type
Example
{}

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" "stream_id" "source" "top_match" "match_result" "face_detections" "face_id" "attach_result" "gender" "age" "emotion" "ethnic_group" "liveness" "deepfake" "body_detections" "body_basic_attributes" "upper_body" "lower_body" "accessories" "tags" "user_data" "location" "mask" "track_id" "meta"
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,null

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

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

List of comma-separated stream IDs.

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) [ items <= 36 characters ^[^\x00]*$ ]
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.

integer or null_filter (string)
Example: gender=1

Gender. 1 - male, 0 - female, "null" - null value .

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

Comma-separated list of predominant emotions or null. 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 and null (1, 2, 3, null)>
Example: masks=1,2,3,null

Comma-separated list of predominant masks or null. 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 and null (1, 2, 3, 4, null)>
Example: ethnic_groups=1,2,null

Comma-separated list of dominant ethnic group or null. 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 and null (0, 1 ,2, null)>
Example: liveness=1,2,null

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

liveness value
spoof 0
real 1
unknown 2
deepfake
string <list of integer and null (0, 1, null)>
Example: deepfake=1,2,null

Comma-separated list of dominant deepfakes or null. Each event from result will contain one of the given deepfake.

deepfake value
fake 0
real 1
Array of integers or null_filter (string)
Example: apparent_gender=1

Comma-separated list of apparent gender: 0 - female, 1 - male, 2 - undefined, "null" - null value. 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.

Array of integers or null_filter (string)
Example: headwear_states=1

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

Array of headwear_color (string) or null_filter (string)
Example: headwear_apparent_colors=white,undefined,null

Comma-separated list of headwear apparent colors or null value. Each event from result will contain one of the given states.

sleeve_lengths
Array of strings
Items Enum: "short" "long" "undefined" null
Example: sleeve_lengths=short,null

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

Array of clothing_color (strings) or null_filter (string)
Example: upper_clothing_colors=black,white

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

lower_garment_types
Array of strings
Items Enum: "undefined" "trousers" "shorts" "skirt" null
Example: lower_garment_types=trousers,undefined,null

Comma-separated list of lower garment types or null value. Each event from result will contain one of the given types.

Array of clothing_color (strings) or null_filter (string)
Example: lower_garment_colors=black,white

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

Array of shoes_color (string) or null_filter (string)
Example: shoes_apparent_colors=white,undefined,null

Comma-separated list of shoes apparent colors or null value. Each event from result will contain one of the given states.

Array of integers or null_filter (string)
Example: backpack_states=1

Comma-separated list of backpack states: 0 - absent, 1 - present, 2 - undefined, "null" - not specified. 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. Events in response will be sorted by their ids. If neither event_id__lt or event_id__gte is specified, the faces will be sorted by creation time.

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

Upper excluding event ID boundary. Events in response will be sorted by their ids. If neither event_id__lt or event_id__gte is specified, the faces will be sorted by creation time.

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 [ items <= 36 characters ^[^\x00]+$ ]
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,null

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

areas
string
Example: areas=CAO,central park,null

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

districts
string
Example: districts=mitino,central park,null

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

streets
string
Example: streets=arbat,schepkina,null

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

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

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

longitude (number) or null_filter (string)
Example: origin_longitude=36.616

Longitude origin in degrees, a part of composite geo position filter or null for undefined geo position. 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. Null filter applied only if origin_longitude or origin_latitude is set to 'null', and longitude_delta and latitude_delta is not set.

latitude (number) or null_filter (string)
Example: origin_latitude=55.752

Latitude origin in degrees, a part of composite geo position filter or null for undefined geo position. 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. Null filter applied only if origin_longitude or origin_latitude is set to 'null', and longitude_delta and latitude_delta is not 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.

string or null_filter (string)
Example: track_ids=track_id1,track_id_2, null

List of comma-separated track IDs.

string or null_filter (string)
Example: meta.field_1__gt:numeric=36.6&meta.field_2.field_3__in=value,none&meta.field_4:integer=5

User-defined event meta's filters.

Parameter name pattern: meta.<path.to.field>__<operator>:<type>

Path to field is an event meta's json field path. To navigate through nested objects the dot (.) is used.

Field comparison operator is optional one of eq (default), neq, like, nlike, in, nin, gt, gte, lt, lte.

Field data type is optional one of string (default), integer, numeric.

Allowed usage of filters is:

operator type
none string integer numeric
eq + + + +
neq + + + +
like - + - -
nlike - + - -
in + + + +
nin + + + +
gt - + + +
gte - + + +
lt - + + +
lte - + + +
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
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-Account-Id
required
string <uuid> ^[a-f0-9]{8}-?[a-f0-9]{4}-?4[a-f0-9]{3}-?[89a...
Example: 8b8b5937-2e9c-4e8b-a7a7-5caf86621b5a

Luna account Id. Designed to identify the created object.

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:
Array (non-empty)
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> (event_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Event ID.

handler_id
required
string <uuid> (handler_id) ^[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 or null <= 36 characters ^[^\x00]*$
Default: ""

user-defined external id for face

user_data
string or null <= 128 characters ^[^\x00]*$
Default: ""

user data.

object or null

User defined metadata (json object). Size shouldn't exceed 2MB.

source
string or null^[^\x00]*$

Additional information that user provides with event.

stream_id
string or null <uuid> (stream_id) ^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]...

Stream ID.

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

Event track ID.

tags
Array of strings or null

Tag array.

object or null

Face object.

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

Matches list.

Array of objects

Detection list.

object (input_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
[
  • {
    }
]

Response samples

Content type
Example
{}

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
{
  • "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 + - - - +
stream_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 + + + + +
deepfake + + + + +
user_data + - - - +
tags + + + - -
city + - - - +
area + - - - +
district + - - - +
street + - - - +
house_number + - - - +
geo_position + - - - -
track_id + - - - +
apparent_age + + + + +
apparent_gender + + + + +
sleeve_length + - - - +
headwear_state + + + + +
upper_clothing_colors + - - - -
backpack_state + + + + +
lower_garment_colors + - - - -
headwear_apparent_color + - - - +
lower_garment_type + - - - +
shoes_apparent_color + - - - +
meta.* + + + + -
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 eq/neq null
tags + - - - - -
source - + + - - +
stream_id - + + - - +
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 - + + + - +
deepfake - + + + - +
city - + + - - +
area - + + - - +
district - + + - - +
street - + + - - +
house_number - + + - - +
geo_position - - - - + +
track_id - + + - - +
apparent_age - + + + - +
apparent_gender - + + + - +
sleeve_length - + + - - +
headwear_state - + + + - +
upper_clothing_colors - + - - - +
backpack_state - + + + - +
lower_garment_colors - + - - - +
headwear_apparent_color - + + - - +
lower_garment_type - + + - - +
shoes_apparent_color - + + - - +
meta.* + + + + - +

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
  1. 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": [
    ]
}

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
{
  • "INFLUX_MONITORING": {
    }
}

plugins

get list of plugins

Get list of service plugins

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
{
  • "plugins": [
    ]
}

metrics

get service requests statistics

Get statistics of success and failed requests to the service in prometheus format.

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
text/plain
# HELP request_count_total Counter of requests
# TYPE request_count_total counter
request_count_total{path="GET:/healthcheck",status_code="200"} 1.0

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
}