API Reference / Get a live session and its results
API Reference

Get a live session and its results

GET/api/v1/live/sessions/{id}

The session. For url sessions also the samples checked since after (poll with the last seq you saw). Polling keeps the session paid and notices when the stream ends. Camera sessions return entries: []: their results come back from each frame.

Path parameters#

Parameter Type Description
id required integer Session id.

Query parameters#

Parameter Type Description
after integer Return only samples with a seq greater than this. Default: 0.

Responses#

200#

The session and new samples.

  • session object (LiveSession) required

    The session, as it is now.

  • entries array of LiveEntry required

    Samples checked since after (stream sessions only).

  • latestFrame object

    Stream URL sessions: the newest sample's picture, so a live view needs no second request. Absent when no new sample has a picture.

session (LiveSession)

  • id integer required

    Session id.

  • source string required

    One of: url, camera. url (a stream watched by our servers) or camera (frames you send).

  • url string or null required

    The stream address; null for camera sessions.

  • fps number required

    Frames checked per second.

  • mode string required

    One of: detect, capture, censor. detect, capture or censor.

  • censorStyle string or null required

    One of: blur, pixelate, box, null. How the moments' censored copies hide what was found; null unless mode is censor.

  • tracking boolean required

    Whether findings are followed from frame to frame (see tracking when starting).

  • frameSide integer required

    Long side, in pixels, of the pictures kept.

  • momentEvery integer required

    Seconds at least between two kept moments.

  • status string required

    One of: running, stopped, ended, failed. stopped: by you or when the credits ran out. ended: the stream ended. failed: the stream could not be watched.

  • reason string or null required

    Why the session is no longer running.

  • framesChecked integer required

    Frames checked so far.

  • framesFlagged integer required

    Frames that raised at least one flag.

  • moments integer required

    Flagged frames kept, with their picture, in your moderation history.

  • creditsCharged integer required

    Credits taken from your balance for the session. While it runs this includes the minute held ahead; when it ends, what its frames did not use goes back and this is what the session cost.

  • creditsUsed integer required

    What the frames checked so far cost: each frame costs costPerMinute / (60 x fps), rounded up to whole credits for the session, and never more than creditsCharged. Equal to creditsCharged once the session has ended.

  • costPerMinute integer required

    What a minute at the session's rate costs: the credits held ahead each minute.

  • startedAt integer required

    Unix time, seconds.

  • endedAt integer or number or null required

    Unix time, seconds; null while running.

  • jobId integer or null required

    The session's entry in your moderation history.

  • width integer

    Stream sessions while running: the stream's width.

  • height integer

    Stream sessions while running: the stream's height.

  • flags array or null required

    The flags checked on every frame, as chosen at the start; null: every flag.

  • metadata object

    The session's metadata, unchanged, when you sent one.

entries[] (LiveEntry)

  • seq integer required

    Sample number, increasing.

  • t number required

    Seconds since the stream started.

  • at number required

    Unix time, seconds.

  • frame boolean required

    true when its picture can be fetched with Get a stream sample's picture.

  • flagged boolean required

    true when the sample raised at least one flag.

  • flags array of FlagResult required

    The flags raised, as in a moderation result.

  • unchecked array of string required

    Flags that could not be checked for this sample.

  • moment integer

    Set when this sample was kept as a moment: the moment's id in your history.

flags[] (FlagResult)

  • flag string required

    The flag's key, one of those GET /api/v1/flags lists. See Flags.

  • confidence number required

    The highest confidence among the flag's detections. From 0 to 1.

  • detections array of Detection

    The flag's findings, strongest first. Not present in detect mode. For text and image flags they have no position.

detections[] (Detection)

  • label string required

    The model's own label for the finding (informational; may change). Use flag for decisions.

  • confidence number required

    How sure the model is. From 0 to 1.

  • bbox array of number

    Images and videos, for a flag with positions: the box [x1, y1, x2, y2] in pixels of the original image or video frame.

  • polygon array of array of number

    Images and videos, when the model outlines the finding: its outline as [x, y] points in original pixels.

  • t number

    Videos, for a flag with positions: seconds from the start of the video.

  • frame integer

    Videos, for a flag with positions: the index of the sampled frame.

  • track integer

    With tracking: the object this finding belongs to. The same object keeps the same number across frames. From 1.

  • tracked boolean

    With tracking: true when a model missed the object in this frame and tracking carried it over. Its confidence is the object's best.

  • start number

    Text: start of the span, a Unicode code point index (inclusive). Audio: seconds.

  • end number

    Text: end of the span, a Unicode code point index (exclusive). Audio: seconds.

  • text string

    Audio: the words.

latestFrame

  • seq integer required

    The sample the picture belongs to.

  • jpeg string required

    The picture, base64-encoded JPEG (the newest checked sample of the stream).

401#

Missing, unknown, revoked or expired API key, or the account is not active.

{
  "error": "unauthorized",
  "message": "The API key is not valid."
}

403#

The key may not do this: a read key on a write endpoint, or a restricted key.

{
  "error": "forbidden",
  "message": "This API key does not have write permission"
}

404#

No session with this id for this account.

{
  "error": "not_found",
  "message": "No such live session."
}

429#

Too many requests in a minute. Wait Retry-After seconds. See Rate limits.

Header Retry-After: Seconds to wait.

{
  "error": "too_many_requests",
  "message": "Too many requests. Try again in a minute."
}

Request

curl -X GET https://api.detectivision.ai/api/v1/live/sessions/{id} \
  -H "Api-Key: $DETECTIVISION_API_KEY"
import os, requests

r = requests.get(
    "https://api.detectivision.ai/api/v1/live/sessions/{id}",
    headers={"Api-Key": os.environ["DETECTIVISION_API_KEY"]},
)
print(r.status_code, r.json())
const res = await fetch("https://api.detectivision.ai/api/v1/live/sessions/{id}", {
  method: "GET",
  headers: {
    "Api-Key": process.env.DETECTIVISION_API_KEY,
  },
});
console.log(res.status, await res.json());

Response 200

{
  "session": {
    "id": 31,
    "source": "url",
    "url": "rtsp://cams.example.com/live",
    "fps": 1,
    "mode": "capture",
    "censorStyle": null,
    "tracking": false,
    "frameSide": 1280,
    "momentEvery": 3,
    "status": "running",
    "reason": null,
    "framesChecked": 13,
    "framesFlagged": 1,
    "moments": 1,
    "creditsCharged": 2,
    "creditsUsed": 1,
    "costPerMinute": 2,
    "startedAt": 1790505000,
    "endedAt": null,
    "jobId": 2210,
    "width": 1920,
    "height": 1080
  },
  "entries": [
    {
      "seq": 12,
      "t": 11.02,
      "at": 1790505012.4,
      "frame": true,
      "flagged": false,
      "flags": [],
      "unchecked": []
    },
    {
      "seq": 13,
      "t": 12.01,
      "at": 1790505013.4,
      "frame": true,
      "flagged": true,
      "flags": [
        {
          "flag": "smoking",
          "confidence": 0.84,
          "detections": [
            {
              "label": "smoking",
              "confidence": 0.84,
              "bbox": [
                410,
                220,
                520,
                330
              ]
            }
          ]
        }
      ],
      "unchecked": [],
      "moment": 2231
    }
  ]
}