Skip to main content

Get bulk plays for a series or puzzle

GET 
/api/v2/analytics/plays

Retrieves play-by-play data in bulk across all users for a series or for a specific puzzle. Intended for high-throughput bulk pulls (data exports, downstream analytics pipelines, dashboards).

For per-user play history, use the separate /api/v2/plays endpoint, which accepts a userId parameter. User-scoped retrieval is not supported on this endpoint.

Supported Modes: Determined by the presence of the puzzleId query parameter:

  • All plays in a series: omit puzzleId — returns every play across every puzzle in the series.
  • All plays for a single puzzle: include puzzleId — returns every user's play on that puzzle.

Puzzle Type Support:

  • Grid Games (Crossword, Codeword, KrissKross, Sudoku): Box completion statistics
  • Quiz Games: Question attempt statistics
  • Word Search & Word Flower: Word finding progress
  • Jigsaw: Piece placement progress

Time Range Filtering:

  • Use from (inclusive) and/or to (inclusive) to filter plays by start time (startedAt, ISO 8601 format).
  • If neither is provided, all plays are considered.
  • If only from is provided, plays from that time onwards are considered.
  • If only to is provided, plays up to that time are considered.
  • If both are provided, plays between from and to (inclusive) are considered.

Pagination and Ordering: Results are paginated with the limit and offset query parameters and are ordered by startedAt in descending order (most recent starts first). Parameter limit (integer) specifies the maximum number of plays to return per request (default 1000, maximum 1000) and offset denotes the number of plays to skip (in the descending order of startedAt) before starting to return results. To retrieve all the plays using this endpoint:

  1. Call the endpoint with offset=0.
  2. Process the returned plays.
  3. If the hasMore field is set to true, request the next page by increasing offset by limit.
  4. Repeat step 3 until a response returns hasMore field as false, indicating there are no more results.

User Info (Lead-Generation Fields): Set getUserInfo=true to include a userInfo object on each play, containing the lead-generation fields (field_1, field_2, field_3) collected for that user. User info is returned only when the account is configured to collect user information; otherwise the userInfo field is omitted from each play.

Examples:

All plays in a series:

curl -L 'http://localhost:8080/pmm-dev/api/v2/analytics/plays?series=demo-api' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Accept: application/json'

All plays for a single puzzle:

curl -L 'http://localhost:8080/pmm-dev/api/v2/analytics/plays?series=demo-api&puzzleId=123ba400' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Accept: application/json'

Plays in a series with user info:

curl -L 'http://localhost:8080/pmm-dev/api/v2/analytics/plays?series=demo-api&getUserInfo=true' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-H 'Accept: application/json'

Request​

Responses​

Bulk list of plays for the requested series or puzzle. Each play includes common fields and a playProgress object containing puzzle type specific statistics and progress information.