Skip to main content

Get plays for a series or specific puzzles

GET 
/api/v1/plays

Retrieves detailed play-by-play analytics data for puzzles in a series or specific puzzle IDs. Each play includes common fields (userId, startTime, endTime, etc.) along with puzzle type specific state details that contain relevant statistics and progress information.

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 records to return per request and offset denotes the number of records 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.

Use Cases:

  • Streak Computation: Use startedAt and updatedAt combined with playProgress fields to compute user streaks. For example, calculate consecutive days a user has completed puzzles by checking if startedAt and updatedAt fall on the puzzle's publish date and the playProgress.playState indicates completion.
  • Puzzle Details: To get detailed information about the puzzles corresponding to the returned play IDs, use the separate Puzzles API endpoint (/api/v1/puzzles) with the puzzleIds parameter containing the puzzle IDs from the plays response.

Examples:

Single Puzzle Play for given User:

curl -L 'http://localhost:8080/pmm-dev/api/v1/plays?series=demo-api&puzzleIds=123ba400&userId=9f7439e7-ecf1-4c03-ba90-91273f149231' \
-H 'Accept: application/json'

Multiple Puzzle Plays (Comma-separated puzzle ids) for a given User:

curl -L 'http://localhost:8080/pmm-dev/api/v1/plays?series=demo-api&puzzleIds=123ba400,46892ef6&userId=9f7439e7-ecf1-4c03-ba90-91273f149231' \
-H 'Accept: application/json'

All Plays for a given User for a given series:

curl -L 'http://localhost:8080/pmm-dev/api/v1/plays?series=demo-api&userId=9f7439e7-ecf1-4c03-ba90-91273f149231' \
-H 'Accept: application/json'

Request​

Responses​

List of plays with puzzle type specific state details. Each play includes common fields and a playProgress object containing puzzle type specific statistics and progress information.