Displays On Demand measurements

Measurements are the core of the Displays On Demand lifecycle. After you create an asset, you purchase a draft measurement, poll for completion, and then purchase a final measurement to publish the asset. This page covers the purchase and poll contract, the SLA posture, and the publication batch.

Asset CRUD lives on the v2 base https://api2.mworks.com under the /v2/displays/* path. The measurement purchase and poll endpoints live under /v2/viewcast/measurements/* (purchases at /v2/viewcast/measurements/purchase/{type}). For the full endpoint reference, see Displays API reference and Viewcast API reference.

Purchase a measurement

POST /v2/viewcast/measurements/purchase/{type}

Queue a measurement by selecting the purchase type in the path: draft or final. There is no kind body field: the kind concept moved into the path, and a request body that still carries kind returns 400. The request body carries the asset_id of the asset to measure plus a caller-minted measurement_request_id (a UUID) as the idempotency key. The endpoint returns 202 Accepted. The Idempotency-Key header is no longer accepted: sending it returns 400.

curl -X POST https://api2.mworks.com/v2/viewcast/measurements/purchase/draft \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": "vcaJDVDYWSSMHAXVEFYW1DVD2PPFD",
    "measurement_request_id": "550e8400-e29b-41d4-a716-446655440000"
  }'

Response (202):

{
  "data": {
    "asset_id": "vcaJDVDYWSSMHAXVEFYW1DVD2PPFD",
    "kind": "draft",
    "status": "queued"
  }
}

The same shape applies to purchase/final, with "kind": "final" in the response and the 300-credit purchase charge (see below).

Replay safety: measurement_request_id is the idempotency key. Replaying the same measurement_request_id with the same body returns the original queued measurement without queuing a second run or charging a second purchase. Replaying the same id with a different body returns 409 idempotency_mismatch. Mint a fresh UUID for each genuinely new measurement request. The replay promise is evaluated after the credit charge: a same-id replay against an empty wallet returns 402 rather than the cached result, and no credit moves on the 402.

Minting a measurement_request_id (any RFC 4122 UUID; generation is always client-side):

// JS / TS (browser, Node 19+, Cloudflare Workers)
const measurementRequestId = crypto.randomUUID();

# Python
import uuid
measurement_request_id = str(uuid.uuid4())

// Go (github.com/google/uuid)
id := uuid.NewString()

# Ruby (securerandom stdlib)
require 'securerandom'
measurement_request_id = SecureRandom.uuid

// Java
String measurementRequestId = java.util.UUID.randomUUID().toString();

State guard: calling purchase/final while the asset is still in draft state returns 409 (the state machine forbids a final purchase from the current state). You must queue and complete a purchase/draft measurement first, which moves the asset to draft_measured. Only then can you queue purchase/final.

See Purchase flow and credits for the credit costs: 150 credits for a draft purchase, 300 credits for a final purchase, each plus the 1 cr base endpoint cost.

Bulk purchase (batch)

POST /v2/viewcast/measurements/purchase/{draft,final}/batch

To buy measurements for many assets at once, the bulk purchase surface accepts 1 to 100 owned asset_ids per call, synchronously, with one outcome per item in submission order (queued, a skipped:<reason>, or a failed:<reason>). Every item runs exactly the single-purchase flow above, at the same per-item cost, and skipped or failed items bill nothing. See Viewcast batch measurement purchase.

Poll for completion

GET /v2/viewcast/measurements/{asset_id}

Poll this endpoint to check the status of the most recent measurement run. The response includes a status field and, when applicable, a refund_credits field.

curl https://api2.mworks.com/v2/viewcast/measurements/$ASSET_ID \
  -H "Authorization: Bearer ***"

The status field transitions through these values:

Status	Meaning
`queued`	Measurement is waiting to be picked up by the pipeline
`running`	Measurement is actively being computed
`completed`	Measurement finished; check the result body for the outcome (measured, `no_coverage`, or `insufficient_data`)
`failed`	Measurement could not produce any result; purchase credits are auto-refunded

When the status is completed with an informational outcome (no_coverage or insufficient_data) or failed, the refund_credits field reflects the auto-refunded purchase amount. See Purchase flow and credits for the refund rules.

Turnaround

Draft measurements complete through the normal production pipeline:

A draft purchase queues (202 returned, 150 credits charged) and completes to a measured result through the normal production path. A completed draft measurement auto-progresses the asset from draft to draft_measured.
The no_result_timeout window still applies: if a queued measurement does not complete within the timeout, the purchase charge is auto-refunded. The base 1 cr endpoint cost is not refunded.

Monday-noon-Eastern final publication batch

Final measurements are published through a batch that runs on Monday at noon Eastern time. The batch processes all assets that have reached draft_measured and have a queued final measurement, moving them to final_measured and minting their display_id.

A final purchase queues the run (202), the purchase completes through the live pipeline, and the final publication transition to final_measured rides the Monday-noon-Eastern batch. Expect the draft_measured to final_measured transition, and the minted display_id, to land on the next batch run after the final measurement completes.

Auto-progression and the auto_progress_final caller hold

A completed draft measurement auto-progresses the asset from draft to draft_measured. The caller does not need to take any action to trigger this transition; it happens automatically when the draft result lands.

However, the progression from draft_measured to final_measured requires the caller to explicitly purchase a final measurement. This is the auto_progress_final caller hold: the API does not automatically queue or purchase a final measurement. The caller decides when (and whether) to spend the 300 credits to publish the asset as a final, viewable inventory record.