GraphQL samples

These queries and subscriptions come from real integrations and run unchanged against the built-in GraphQL IDE at http://localhost:8097/graphql (or http://graphql-api:8080/graphql from a container). Paste the variables into the IDE's GraphQL Variables panel. Remember the 1000-item limit per response described in GraphQL API: every sample below takes take and skip so you can page.

Queries

Faces with matches in a time range

Returns every face that matched a watchlist member between $from and $to, with the member, the tracklet, the frame and the crop coordinates of the face within the frame.

query GetAllFacesWithMatches($take: Int, $skip: Int, $from: DateTime!, $to: DateTime!) {
  faces(
    take: $take
    skip: $skip
    order: { createdAt: ASC }
    where: {
      and: [
        { createdAt: { gte: $from } }
        { createdAt: { lte: $to } }
        { matchResults: { any: true } }
      ]
    }
  ) {
    items {
      id
      createdAt
      imageDataId
      matchResults {
        watchlistMemberId
        watchlistMemberFullName
      }
      tracklet { id }
      frame { id imageDataId }
      cropLeftTopX
      cropLeftTopY
      cropRightBottomX
      cropRightBottomY
    }
  }
}

Appearances of an identified person

The basis of an attendance report: all match results for one member across all cameras and edge streams, with the stream where each appearance happened.

query GetAppearancesOfIdentifiedPerson($watchlistMemberId: String, $take: Int, $skip: Int, $from: DateTime!, $to: DateTime!) {
  matchResults(
    take: $take
    skip: $skip
    order: { createdAt: ASC }
    where: {
      and: [
        { watchlistMemberId: { eq: $watchlistMemberId } }
        { createdAt: { gte: $from } }
        { createdAt: { lte: $to } }
      ]
    }
  ) {
    items {
      id
      createdAt
      watchlistMemberId
      watchlistMemberDisplayName
      stream { id name }
    }
  }
}

{
  "watchlistMemberId": "67a45ede-ed09-4074-b5c0-8d0514ee18fe",
  "from": "2026-09-01T00:00:00Z",
  "to": "2026-09-01T23:59:00Z",
  "skip": 0,
  "take": 10
}

Pedestrians linked to identified faces

When object linking is on (ObjectLinking__Enabled=true, the default), each pedestrian detection is linked to the face detected on the same body. This query returns pedestrians whose face matched a watchlist, together with the pedestrian bounding box, which is what you need to draw the whole person rather than just the face. pageInfo supports cursor-style paging through the whole history.

query PedestriansWithIdentifiedFace($take: Int, $skip: Int, $from: DateTime!, $to: DateTime!) {
  pedestrians(
    take: $take
    skip: $skip
    where: {
      processedAt: { gte: $from, lte: $to }
      face: { matchResults: { some: { watchlistId: { neq: null } } } }
    }
  ) {
    items {
      face {
        matchResults {
          watchlistMemberDisplayName
          watchlistMemberFullName
          watchlistId
        }
      }
      processedAt
      streamId
      cropLeftTopX
      cropLeftTopY
      cropRightBottomX
      cropRightBottomY
    }
    pageInfo { hasNextPage hasPreviousPage }
  }
}

Pedestrians by attributes

Pedestrian attributes are stored as objectAttributes with a type and a boolean or float value. Combine several some filters with and to build a description: here adult men wearing long sleeves and glasses and carrying a backpack.

query PedestriansFiltered {
  pedestrians(
    where: {
      and: [
        { objectAttributes: { some: { type: { in: [LONG_SLEEVE] } } } }
        { objectAttributes: { some: { type: { in: [GLASSES] } } } }
        { objectAttributes: { some: { type: { in: [IS_ADULT] } } } }
        { objectAttributes: { some: { type: { in: [IS_MALE] } } } }
        { objectAttributes: { some: { type: { in: [BACKPACK] } } } }
      ]
    }
  ) {
    items {
      id
      objectAttributes { type floatValue boolValue }
    }
  }
}

Search the face history by image

Finding where a given person appeared takes two calls: the REST API starts a search session over all stored faces, and GraphQL reads the results. Send POST http://localhost:8098/api/v1/Faces/Search with the image:

{
  "image": { "data": "/9j/4AAQSkZJRgABAQEAYABgAAD..." },
  "threshold": 50,
  "maxResultCount": 100
}

The response is a search session identifier:

{ "searchSessionId": "3f21a452-eb05-4f6a-a692-e77931c1cfba" }

Then query the faces that belong to that session, each with the similarity score the search assigned:

query SearchByImageResults {
  faces(
    where: {
      searchSessionObjects: {
        some: { searchSessionId: { eq: "3f21a452-eb05-4f6a-a692-e77931c1cfba" } }
      }
    }
  ) {
    items {
      searchSessionObjects { score searchSessionId }
      createdAt
      quality
      age
      id
      imageDataId
      matchResults { score }
      frame {
        id
        imageDataId
        stream { id name }
      }
    }
    totalCount
  }
}

Search sessions are cleaned up automatically; see Face search for the retention setting and the difference between searching history and identifying against watchlists.

Subscriptions

Members of a restricted watchlist

Filter matchResult on the watchlist to be told only when a member of a particular list is seen. Match on the identifier (where: { watchlistId: { eq: "..." } }) in production; matching on the name is convenient while testing.

subscription RestrictedPersonDetected {
  matchResult(where: { watchlistFullName: { contains: "Restricted" } }) {
    createdAt
    streamId
    watchlistId
    watchlistFullName
    watchlistMemberId
    watchlistMemberFullName
    watchlistMemberDisplayName
  }
}

Every detected face

faceProcessed fires for every face the detectors produce, matched or not, with the crop coordinates and, when there was a match, the member information. It is a direct notification, so it arrives before the face is stored.

subscription AnyFaceDetected {
  faceProcessed {
    faceInformation {
      cropCoordinates { cropLeftTopX cropLeftTopY }
    }
    matchInformation { fullName }
  }
}

Faces by extracted attribute

faceExtracted fires once the face attributes (age, gender, face mask) have been extracted and stored, so you can filter on them. This example notifies on faces estimated to be under 18, whether or not they matched.

subscription FaceUnder18Detected {
  faceExtracted(where: { age: { lt: 18 } }) {
    createdAt
    age
    faceArea
    type
  }
}