# Read listening activity

Source: https://recoupable.dev/docs/api-reference/players/activity

Read player listening activity

## GET /api/players/{id}/activity

Full OpenAPI specification: https://recoupable.dev/docs/spec/players.json

## Authentication

This operation requires one of the security alternatives in the specification below. Security scheme definitions are included where present in the published specification.

[Authentication guide](https://recoupable.dev/docs/authentication)

## Operation and referenced schemas

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Recoup API - Release Players",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.recoupable.dev"
    }
  ],
  "paths": {
    "/api/players/{id}/activity": {
      "get": {
        "summary": "Read player listening activity",
        "description": "Private 30-day summary plus up to 100 events, newest first. Returns measurement=browser_reported_playback, dspStreams=null, periodDays, offset, limit and report (sessions, connectedFans, reportedListeningMs, playEvents, campaigns, activity). Activity has session_id, provider, track_id, event, position_ms, listened_ms, received_at, fan_id and display_name. Anonymous Apple sessions have no fan identity. These are reported SDK observations, not DSP stream counts, cross-device monitoring, or causal uplift. MCP: get_release_player_activity.",
        "security": [
          {
            "apiKeyAuth": []
          },
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "organizationId",
            "in": "query",
            "schema": {
              "type": [
                "string",
                "null"
              ],
              "format": "uuid",
              "description": "Authorized workspace; omit for the authenticated account. Never send account_id."
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "PlayerReportResponse fields returned by the release player service.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerReportResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid authentication or failed provider authorization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          },
          "403": {
            "description": "Workspace, origin, or session access denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          },
          "404": {
            "description": "Player not available",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          },
          "429": {
            "description": "Request rate limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          },
          "503": {
            "description": "Feature/configuration temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlayerError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PlayerReportResponse": {
        "type": "object",
        "properties": {
          "measurement": {
            "type": "string",
            "const": "browser_reported_playback"
          },
          "dspStreams": {
            "type": "null"
          },
          "periodDays": {
            "type": "integer",
            "const": 30
          },
          "offset": {
            "type": "integer",
            "format": "int64"
          },
          "limit": {
            "type": "integer",
            "const": 100
          },
          "report": {
            "type": "object",
            "properties": {
              "sessions": {
                "type": "integer",
                "format": "int64"
              },
              "connectedFans": {
                "type": "integer",
                "format": "int64"
              },
              "reportedListeningMs": {
                "type": "integer",
                "format": "int64"
              },
              "playEvents": {
                "type": "integer",
                "format": "int64"
              },
              "campaigns": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "provider": {
                      "type": "string"
                    },
                    "source": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "campaign": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "sessions": {
                      "type": "integer",
                      "format": "int64"
                    },
                    "listened_ms": {
                      "type": "integer",
                      "format": "int64"
                    }
                  },
                  "required": []
                }
              },
              "activity": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PlayerActivity"
                }
              }
            },
            "required": [
              "sessions",
              "connectedFans",
              "reportedListeningMs",
              "playEvents",
              "campaigns",
              "activity"
            ]
          }
        },
        "required": [
          "measurement",
          "dspStreams",
          "periodDays",
          "offset",
          "limit",
          "report"
        ],
        "description": "Reporting envelope uses camelCase. Nested activity and campaign rows intentionally expose raw database snake_case fields."
      },
      "PlayerError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "error"
        ]
      },
      "PlayerActivity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "event": {
            "type": "string"
          },
          "provider": {
            "type": "string",
            "enum": [
              "spotify",
              "apple_music"
            ]
          },
          "track_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "position_ms": {
            "type": "integer",
            "format": "int64"
          },
          "listened_ms": {
            "type": "integer",
            "format": "int64"
          },
          "received_at": {
            "type": "string",
            "format": "date-time"
          },
          "fan_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "contact_id": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          }
        },
        "required": [
          "id",
          "session_id",
          "event",
          "provider",
          "listened_ms",
          "received_at"
        ],
        "description": "Raw database reporting row; snake_case keys are preserved intentionally."
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key"
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}
```