Get a test play
get/v1/test_helpers/plays/{test_play_id}
A test play and how far it has got: queued (accepted), sending
(its evidence is going out), sent (all of it has gone; the pipeline
is matching it), matched (play_id is the real play: read it with
GET /v1/plays/{play_id}), or failed (failure says why). A
no_evidence play stays sent with a null play_id.
Access
- Authentication
- Secret key or OAuth access token.
- Scope
test_helpers:write- User permission
developerAccess
Path parameters
test_play_idstringRequired
Headers
Vojo-VersionstringOptional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the
Vojo-Versionresponse header. Within/v1only additive changes ship, so most callers can omit it.
Response 200
OK
dataobjectRequiredShow 11 fields
idstringRequiredPrefixed
tplay_.statusstringRequiredscenariostringRequiredWhat evidence a test play sends; see
createTestPlayfor the score each settles at.expected_scoreinteger or nullRequiredThe score this scenario settles at; null for
no_evidence. The real play's own score is on the play.screen_idstringRequiredadvertisement_idstringRequiredplay_idstring or nullRequiredThe real play, once the matcher has opened it; read it with
GET /v1/plays/{play_id}.failureobject or nullRequiredWhy a
failedtest play failed; null otherwise.Show 2 fields
codestringRequiredmessagestringRequired
created_atstringRequiredsent_atstring or nullRequiredWhen the last of its evidence went out.
livemodebooleanFalse for an object in an integrator sandbox (test key), true otherwise. Always set on each object directly under
data; absent on the same kind of object nested inside another.
metaobjectRequired
Response headers
Vojo-VersionstringThe API version (date) this response was rendered with — the request's
Vojo-Version, else the key/org pin.RateLimitstringIETF RateLimit header: remaining quota in the current window, e.g.
"default";r=97;t=42.RateLimit-PolicystringIETF 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-Afterseconds. - 500
Unexpected server failure.