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

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.