A Placecast Select scenario is submitted as a JSON request that defines the places to measure, the time periods of interest, the cohort to profile, and the runtime version to run. Each request creates one scenario; results are returned as a single response object.

Request Structure

{
  "motionworks_scenario_id": "C42AA2BB-173F-423E-9AFF-518BB9D7486C",
  "name": "Atlantic City Boardwalk - 2024-01-02",
  "description": "Atlantic City Boardwalk - 2024-01-02",
  "periods": [
    {
      "period_name": "2024-01-02 12:00 AM - 2024-01-02 11:45 PM",
      "start_time": "2024-01-02T05:00:00+00:00",
      "end_time": "2024-01-03T04:45:00+00:00"
    }
  ],
  "place_ids": [
    "276411"
  ],
  "cohort": {
    "geography_ids": [
      "XX2020NATNUS"
    ],
    "motionworks_segment_id": "2ad53adfc6677f71"
  },
  "customer": {
    "customer_id": "203",
    "customer_name": "All Points Media",
    "customer_scenario_name": "Atlantic City Boardwalk - 2024-01-02",
    "customer_scenario_info": "Atlantic City Boardwalk Info - 2024-01-02",
    "customer_scenario_id": "C42AA2BB-173F-423E-9AFF-518BB9D7486C"
  },
  "timezone": "America/New_York",
  "runtime_version": "2.4",
  "include_cohort_metrics": true,
  "include_confidence_interval": true
}

Schema

Name	Description	Type	Example
motionworks_scenario_id	Required. Unique identifier for the scenario across Motionworks systems. Reusing an existing identifier overwrites the prior scenario.	string	C42AA2BB-173F-423E-9AFF-518BB9D7486C
name	Optional user-defined name for the scenario.	string	Atlantic City Boardwalk - 2024-01-02
description	Optional user-defined description for the scenario.	string	Atlantic City Boardwalk - 2024-01-02
periods	Required. Array of time periods to measure. Each place is measured across every period in the array.	array of objects	See example above
periods[]. period_name	User-defined label for the period.	string	2024-01-02 12:00 AM - 2024-01-02 11:45 PM
periods[]. start_time	Period start, ISO-8601 timestamp. Interpreted against timezone.	string (ISO-8601)	2024-01-02T05:00:00+00:00
periods[]. end_time	Period end, ISO-8601 timestamp. Interpreted against timezone.	string (ISO-8601)	2024-01-03T04:45:00+00:00
place_ids	Required. Array of Motionworks place identifiers to measure. Supply a single place or a place set.	array of strings	["276411"]
cohort	Optional cohort definition. When omitted, the scenario profiles all persons nationally and returns the top segments.	object	See example above
cohort. geography_ids	Home-geography scope for cohort metrics. National (XX2020NATNUS), state, DMA, county, or ZCTA identifiers.	array of strings	["XX2020NATNUS"]
cohort. motionworks_segment_id	Specific population, consumer, or PRIZM segment to guarantee in the response. Top segments are returned regardless; supply an id to ensure a given segment is included. See Population, Consumer, and PRIZM segment references.	string	2ad53adfc6677f71
customer	Customer and scenario tracking metadata. Stored with the scenario and echoed on the response.	object	See example above
customer. customer_id	Required. Motionworks customer identification number. Contact Motionworks for your customer id.	string	203
customer. customer_name	Customer organization name.	string	All Points Media
customer. customer_scenario_name	Human-readable scenario name for customer use.	string	Atlantic City Boardwalk - 2024-01-02
customer. customer_scenario_info	Free-form notes or metadata about the scenario.	string	Atlantic City Boardwalk Info - 2024-01-02
customer. customer_scenario_id	Required. Customer-provided identifier for the scenario, for customer-side tracking.	string	C42AA2BB-173F-423E-9AFF-518BB9D7486C
timezone	Required. IANA timezone of the periods and places. Period timestamps are interpreted in this timezone, and day-of-week / hour-of-day reporting uses it.	string	America/New_York
runtime_version	Placecast Select version to run, given as 2.2, 2.3, or 2.4 (the v2_2 / v2_3 / v2_4 form is also accepted). Defaults to 2.4. An unrecognized value falls back to 2.4. Versions differ in their multiplier tables, dwell-time thresholds, and supported date coverage.	string	2.4
include_cohort_metrics	Whether to compute cohort-filtered metrics (the non-_total metric variants). Defaults to false.	boolean	true
include_confidence_interval	Whether to compute the *_ci confidence intervals. Defaults to false.	boolean	true
project	Optional identifier of a specific project, obtained from the project-list endpoint. Supplied as a URL parameter, not in the request body.	string	64b5968db4b3cd0012d66b50

Validation Rules

• Period date floor: Each runtime version enforces the earliest period start it will measure. v2_4 only accepts periods starting on or after 2024-09-01; versions without a configured floor accept periods on or after 2019-01-01. Scenarios whose earliest period starts before the floor are returned with all metrics nulled and an Error: Scenario period starts before … message.
• Timezone alignment: timezone should match the timezone of the place or places in the scenario. Period start and end times are interpreted in this timezone.
• Place validity: Place identifiers must resolve to valid, focused Motionworks places. Places that are invalid or unfocused are dropped and listed in the response's messages.dropped_places; a scenario with no valid focused places returns an error.
• Rate limit: Clients may create up to 1,000 scenarios per 24 hours. The count resets at 12:00 AM US Eastern Time each day.