Get a play

get/v1/plays/{play_id}

A single play with its track statuses and trust score.

curl "https://api.vojo-media.com/v1/plays/$PLAY_ID" \
  -H "Authorization: Bearer $VOJO_KEY"

const { data, error } = await api.GET("/v1/plays/{play_id}", {
  params: { path: { play_id: playId } },
});
if (error) throw new VojoApiError(error);

Response 200

{
  "data": {
    "id": "vp_cm1vpl4k8s0001d2f6g9h3j5kq",
    "screen_id": "cm1scr2w6n0001h8d4k9t3m7ve",
    "screen": {
      "id": "cm1scr2w6n0001h8d4k9t3m7ve",
      "name": "Lobby North"
    },
    "advertisement_id": "cm1adv3z7x0001c5v9b2n6m4tm",
    "advertisement": {
      "id": "cm1adv3z7x0001c5v9b2n6m4tm",
      "name": "Autumn launch 15s"
    },
    "external_play_id": "admitt-imp-88213",
    "channel": "admitt",
    "started_at": "2026-10-07T09:00:00Z",
    "tracks": {
      "passport": "matched",
      "harvester": "absent"
    },
    "verification": {
      "score": 82,
      "band": "high",
      "phase": "final",
      "scored_at": "2026-10-07T09:15:02Z"
    },
    "created_at": "2026-10-07T09:00:01Z",
    "updated_at": "2026-10-07T09:15:02Z"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: plays:read
User permission: advertisementViewStats

Path parameters

play_idstringRequired

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date

Response 200

dataobjectRequired
A play: one showing of a creative, formed from the evidence events that matched it. The trust score breakdown is internal and never exposed.
Show 12 fields
- idstringRequired
- screen_idstring or nullRequired
  Null when the play happened on a screen not registered in Vojo (e.g. an exchange's own screen).
- screenobject or nullRequired
  The play's screen with its name, so lists render without a lookup per row; null when screen_id is null.
  Show 2 fields
  - idstringRequired
  - namestringRequired
- advertisement_idstring or nullRequired
- advertisementobject or nullRequired
  The play's advertisement (creative) with its name; null when advertisement_id is null.
  Show 2 fields
  - idstringRequired
  - namestringRequired
- external_play_idstring or nullRequired
  The partner's per-play correlation id, echoed verbatim; never verified.
- channelstring or nullRequired
- started_atstringRequired
  Time of the earliest evidence event in the play.
  date-time
- tracksobjectRequired
  Vojo's two independent evidence sources for this play: passport (the in-creative fingerprint) and harvester (the sensor on the glass). Raw per-track status; never collapsed into a single verified flag.
  Show 2 fields
  - passportstringRequired
    One of absent, present, matched
  - harvesterstringRequired
    One of absent, present, matched
- verificationobjectRequired
  Same score, band and phase the verification.score webhook sends.
  Show 4 fields
  - scoreinteger or nullRequired
    Final score once phase is final, else the preliminary score; null before any scoring.
    0 to 100
  - bandstring or nullRequired
    Trust band. Clients must tolerate new values.
    One of low, medium, high, max
  - phasestringRequired
    preliminary scores can still change as evidence arrives; final scores never change.
    One of preliminary, final
  - scored_atstring or nullRequired
    date-time
- created_atstringRequired
  date-time
- updated_atstring or nullRequired
  date-time
metaobjectRequired

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.

Errors

Every error is application/problem+json. Branch on its code.

401
Missing, invalid, expired or revoked credential.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
404
The resource does not exist, or belongs to another organisation. Cross-org ids always 404, never 403.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.