openapi: 3.1.0 x-customer-voice: true info: title: Placecast Select version: 0.4.0 description: | Purchase, poll, and retrieve a reach-and-frequency analysis for an event scenario — Placecast Select. Creating and managing the event scenario itself — the places, active window, and audience it describes — is a separate endpoint family at `/v2/scenarios/events/*` (see the Scenarios reference). Purchasing an analysis is asynchronous: `POST /v2/placecast/measurements/purchase/select` returns `202` with `status: "queued"`; poll `GET /v2/placecast/measurements/{asset_id}` for state. Expect a report roughly one to two days after purchase, not same-day — purchases are batched once daily before analysis starts. Once state is `completed`, the report is available at `GET /v2/placecast/select/{asset_id}`, final and permanently retrievable. A failed run auto-refunds the purchase charge, less a 1-credit charge for the API call itself; the event scenario moves to a `failed` state that stays fully editable and can be purchased again in place. Authenticate with an org-scoped API key (`X-API-Key: mw_…`). Purchasing an analysis costs 30,000 credits. Polling is free; report retrieval costs 1 credit. contact: name: Motionworks AI url: https://mworks.com email: api@mworks.com servers: - url: https://api2.mworks.com/v2 description: Production security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey name: X-API-Key in: header schemas: PlacecastSelectStatus: type: string enum: - queued - running - completed - failed description: | Where the analysis run is: `queued` (accepted, not started), `running`, `completed` (the event asset's report is retrievable) or `failed` (`failure_reason` is populated and the purchase charge is refunded, less a 1-credit charge for the API call itself). PlacecastSelectPurchaseRequest: type: object required: - asset_id - measurement_request_id properties: asset_id: type: string description: The event scenario asset to purchase an analysis for, owned by your organization. measurement_request_id: type: string format: uuid description: | Idempotency key you mint (UUID). A retry with the same key and an identical body replays the original result at no additional charge; the same key with a different body is rejected with `409`. Carried in the request body, not an `Idempotency-Key` header. description: POST /measurements/purchase request body — asset_id rides in the body, not the path. PlacecastSelectResult: type: object required: - measurement_id - asset_id - status - queued_at description: The `202` initial-acceptance body for a purchase. properties: measurement_id: type: string nullable: true description: Null only in the brief poll-before-queue race window. asset_id: type: string status: $ref: '#/components/schemas/PlacecastSelectStatus' queued_at: type: string format: date-time completed_at: type: string format: date-time refund_credits: type: integer description: Populated on `failed` — the purchase charge, refunded less a 1-credit charge for the API call itself (29,999 of the 30,000 credits). failure_reason: type: string PlacecastMeasurementPollResult: type: object required: - asset_id - state - updated_at description: | The current status of an event's measurement run, plus refund details if it failed. properties: asset_id: type: string state: type: string enum: - draft - queued - in_flight - completed - failed refund_credits: type: integer description: 'Populated only on `state: failed`, when a refund ledger row exists.' failure_reason: type: string description: 'Populated only on `state: failed`.' updated_at: type: string format: date-time PlacecastSelectReport: type: object additionalProperties: true description: | The full measurement result for this event, returned exactly as produced by the analysis — every field it contains, with no renaming or restructuring, aside from a short list of internal- only fields removed before the response is served. Because the analysis is refined over time, treat this as an open-ended object rather than a fixed set of fields: new fields can appear, existing ones are not guaranteed to keep a specific structure release to release, and a numeric-looking value may arrive as a string. `run_id`, `disposition` (whether the event was measured or rejected), and `qa_flag` (a quality tier) are currently present on every report. `motionworks_scenario_id` identifies this analysis run; its value is not guaranteed to equal the scenario identifier you supplied when purchasing. Retrievable once the event asset is `completed` (final, permanent). There is no interim report before then. Provenance: type: object properties: source: type: string source_doc: type: string format: uri methodology_version: type: string data_vintage: type: string format: date data_freshness: type: string enum: - hourly - daily - weekly - monthly - annually - on-demand - static data_latency_days: type: integer data_maturity: type: string enum: - production - research-preview - synthetic-only - roadmap Meta: type: object properties: request_id: type: string credits_used: type: integer credits_remaining: type: integer product: type: string version: type: string provenance: $ref: '#/components/schemas/Provenance' Error: type: object properties: error: type: object properties: code: type: string message: type: string status: type: integer request_id: type: string product: type: string docs_url: type: string paths: /placecast/measurements/purchase/select: post: operationId: purchasePlacecastSelect summary: Purchase a Placecast Select analysis description: | Purchases and runs a reach-and-frequency Placecast Select analysis for an event scenario asset you own. `asset_id` rides in the body, not the path. Costs 30,000 credits, charged on acceptance. `202` + `status: "queued"`. Automatically refunded, less a 1-credit charge for the API call itself, if the run fails. Poll `GET /v2/placecast/measurements/{asset_id}` for completion. If the event names a place set (`place_set_id`), the set must be `ready` when you purchase; the purchase counts as a use of the set and extends its expiry to 180 days from now. The run measures the set's contents when it executes, not when you purchase. If the set is deleted or expires before the run starts, the run fails and is refunded. tags: - Measurements x-credit-cost: 30000 x-motionworks-status: production requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PlacecastSelectPurchaseRequest' responses: '202': description: Accepted and queued. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PlacecastSelectResult' meta: $ref: '#/components/schemas/Meta' '400': description: Invalid request, the asset is not in a purchasable state (`draft` or `failed`), or the event's place set is not `ready` (still loading, failed to load, expired, or not found in your organization). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Unknown asset_id, or an asset that does not belong to your organization. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: '`measurement_request_id` reused with a different body.' content: application/json: schema: $ref: '#/components/schemas/Error' /placecast/measurements/{asset_id}: get: operationId: pollPlacecastMeasurement summary: Poll an event asset's measurement state description: | Returns the event asset's current lifecycle state — a dedicated, free poll route on this surface (unlike Viewcast Select, which reuses an existing endpoint; Placecast has no equivalent pre-existing per-asset poll route). 0 credits. tags: - Measurements x-credit-cost: 0 x-motionworks-status: production parameters: - name: asset_id in: path required: true schema: type: string responses: '200': description: Current state. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PlacecastMeasurementPollResult' meta: $ref: '#/components/schemas/Meta' '404': description: Unknown asset_id, or an asset that does not belong to your organization. content: application/json: schema: $ref: '#/components/schemas/Error' /placecast/select/{asset_id}: get: operationId: getPlacecastSelectReport summary: Retrieve a completed Placecast Select report description: | Returns the full measurement result for an event scenario asset once it is `completed` (final, permanently retrievable), exactly as produced by the analysis. There is no interim report before the run completes. 1 credit per call. tags: - Reports x-credit-cost: 1 x-motionworks-status: production parameters: - name: asset_id in: path required: true schema: type: string responses: '200': description: The report. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PlacecastSelectReport' meta: $ref: '#/components/schemas/Meta' '404': description: Unknown asset_id, an asset that does not belong to your organization, or an asset in `draft`, `queued`, or `failed` state (no report to serve yet). content: application/json: schema: $ref: '#/components/schemas/Error' x-tagGroups: - name: Placecast Select tags: - Measurements - Reports tags: - name: Measurements description: Purchase a Placecast Select reach-and-frequency analysis and poll it for completion. - name: Reports description: Retrieve a completed Placecast Select analysis report.