Applications - Detections

The Application Detections endpoint returns the latest assertions on media from either a user or the application's current best model.

Application Detection Objects

Field
media object	A Cogniac Media item.
focus map	(optional) Map or object identifying the portion or subregion of the media, (e.g. a particular box area or range of frames) with which the subject-media association is asserted. If the entire media is processed, this field will be null.
detections array	A list of subject-media assertion objects.
other_media array	(optional) List of other media objects that may be related to this subject-media association.
updated_at float	The timestamp of the latest assertion on this media in the context of this application.

Subject-Media Assertion Object

Field	Example	Description
subject_uid string	"cat_123"	The ID of the subject.
detection_id string	"1hg2Srt8c"	Unique ID of the user or model detection.
user_id string	"[email protected]"	(optional) Username of the user that created the subject-media assertion. If the record is a model assertion this field will be `null`.
model_id string	"Hpo-h-1ec0-to5dGrTAN9QeV6djep-CN_mtsv0_2000.tgz"	(optional) ID of the model that created the subject-media assertion. If the record is a user assertion this field will be `null`.
app_id string	"a765rtyg"	(optional) ID of an application, the context in which the assertion was created. In the case that an assertion was made out of an application context, e.g. a media item was directly captured to a subject, this field will be `null`.
app_data_type string	"box_set"	(optional) String representing the application-type-specific context of the subject-media association.
app_data object	{ "box": {"x0": 20, "y0": 56, "x1": 535, "y1": 249}, "probability": 0.95 }	(optional) Application-type-specific meta data for the subject-media association.
prev_prob float	0.87	(optional) Likelihood of the subject-media (and optional focus) association in the previous assertion.
probability float	0.99	The current likelihood of the association between the subject and the media (plus optional focus). This probability is independent of the app_data, i.e. the overall probability that the subject is associated with the media and focus, regardless of correctness of app_data.
uncal_prob float	1.0	The assertion probability by either a user or model. In the event that the app_data contains multiple predictions this is a single, summarized number for user presentation purposes. Summarization is application specific.
created_at unix timestamp	1234567890	Time at which the assertion was created.

Retrieving Application Detections

The following query parameters are supported:

Argument	Example	Description
start float	1234567890.0	(optional) Unix timestamp. Return media updated after this timestamp. Defaults to 0.
end float	1234567890.0	(optional) Unix timestamp. Return media updated prior to this timestamp. Defaults to current time.
probability_upper float	0.75	(optional) Subject-media association probability ceiling. Defaults to 1.0.
probability_lower float	0.25	(optional) Subject-media association probability floor. Defaults to 0.0.
limit integer	10	(optional) Number of results to return per page. Defaults to 10.
reverse boolean	True	(optional) True = return results in descending order based on assertion timestamp. False = return results in ascending order. Defaults to False.
consensus_none boolean	True	(optional) When set to True, will return only media assertions that have not reached consensus. This is useful for alternate feedback interfaces where it is undesirable to display items that have already reached consensus. Defaults to False.
only_user boolean	True	(optional) When set to True, will return only media assertions made by users. Defaults to False. only_user and only_model cannot both be set to True.
only_model boolean	False	(optional) When set to True, will return only media assertions made by the latest best model. Defaults to False. only_user and only_model cannot both be set to True.

GET /1/applications/{application_id}/detections
Host: https://api.cogniac.io

Example: Retrieve Application Detections

curl -X GET https://api.cogniac.io/1/applications/di71rG94/detections?limit=10&reverse=true \
-H "Authorization: Bearer abcdefg.hijklmnop.qrstuvwxyz"

import cogniac

# connect to the tenant
cc = cogniac.CogniacConnection(username="[email protected]", 
                               password="myPassword", 
                               tenant_id="63QhzFLc9tg4")

# get the app object
my_app = cc.get_application('di71rG94')

# the detections method returns an iterator of app detections
detections = app.detections(limit=10, reverse=True)
for d in detections:
  print d

{
  "data": [
    {
      "detections": [
        {
          "app_data": null,
          "app_data_type": null,
          "app_id": "0Am1V3kr",
          "created_at": 1497662139.841296,
          "detection_id": "QMQYDAVPXP:0",
          "focus": null,
          "media_id": "XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
          "model_id": "Hpo-d-6fa6-2Xg6MZdpxEC2Jvx3K1-YN_mtsv0_4782.tgz",
          "prev_prob": null,
          "probability": 0.001000835148309544,
          "subject_uid": "cat_a1",
          "uncal_prob": 0,
          "user_id": null
        }
      ],
      "media": {
        "author": null,
        "author_profile_url": null,
        "created_at": 1497662135.660577,
        "external_media_id": null,
        "filename": null,
        "frame": null,
        "image_height": 1200,
        "image_width": 800,
        "license": null,
        "md5": "05180dac616104ff004027a5f274d6ad",
        "media_format": "JPEG",
        "media_id": "XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
        "media_src": "twitter",
        "media_timestamp": 1497662135.629489,
        "media_url": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH",
        "meta_tags": ["twitter"],
        "network_camera_id": null,
        "original_landing_url": null,
        "original_url": null,
        "parent_media_id": null,
        "parent_media_ids": [],
        "preview_url": null,
        "resize_urls": {
          "454": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH_max_454",
          "750": "https://cogniac-media.s3.amazonaws.com/XVLNY8FEKGT1VZC3XN2JGS2ZVAWH_max_750"
        },
        "set_assignment": "training",
        "size": 168423,
        "source_url": null,
        "status": "success",
        "tenant_id": "skjdfh853k4jt",
        "title": null,
        "uploaded_by_user": null,
        "video": false
      },
      "focus":{
        "box": {"x0": 50, "x1": 275, "y0": 634, "y1": 870}
      },
      "updated_at": 1497662139.841296
    },
  ...],
  "paging": {
    "next": "https://api.cogniac.io/1/applications/0Am1V3kr/detections?&end=1482263487.41&reverse=False&start=0&limit=5&only_user=False&only_model=False&probability_upper=1.0&probability_lower=0.0&cursor=1481857295.877328&consensus_none=False"
  }

Detection Post URLs

In addition to polling for recent Application detections, you can also specify
callback URLs to receive postback detections in realtime as they occur. Please enter your listening URL's in the detection_post_urls field of the Application object, for example "detection_post_urls":["http://127.0.0.1:9999/my_model_output.net", "https://product_model_detections.co"].

Posts are retried for thirty seconds, but URL's that fail retried posts after thirty seconds are blacklisted for five minutes.

The detection callback post will will only be sent if a subject probability is over the configured detection threshold (0.5 by default).

{
	"media": {"media_id": "dfc37db6723376ab953b10cd40097a68"
            "parent_media_ids": ['c8ee0f4f05f3fdcf36f69a3fd81fd84f'],
           },
  "focus":{
        "box": {"x0": 50, "x1": 275, "y0": 634, "y1": 870}
      },
  "subjects":[
    {
      "subject_uid":"dog",
      "probability":0.79,
      "updated_at": 1481857269.646634
      
    },
    {
      "subject_uid":"cat",
      "probability":0.49,
      "updated_at": 1481857269.646634      
    }  
  ]
}