User Payout Metrics API

The GET /v2/users/{id}/metrics/payouts endpoint returns payout volume metrics for a specific user. Use this endpoint to retrieve historical payout totals for a given timeframe.

GET /v2/users/{id}/metrics/payouts

Retrieves payout volume metrics for a user. The response includes the total payout amount sent to the user within the specified timeframe.

Path Parameters

Parameter	Type	Description
`id`	string	The user identifier (required)

Query Parameters

Parameter	Type	Description
`timeframe`	string	The time window for metrics calculation (optional)

Supported Timeframes

The timeframe parameter accepts the following values:

today — Metrics for the current day
this_week — Metrics for the current week (Monday–Sunday)
this_month — Metrics for the current calendar month
last_7_days — Rolling 7-day window
last_30_days — Rolling 30-day window
last_90_days — Rolling 90-day window
this_year — Metrics for the current calendar year
all_time — All-time metrics for the user

If no timeframe is provided, the endpoint returns metrics for a default period.

Response Fields

Field	Type	Description
`user_id`	string	The user identifier
`timeframe`	string	The timeframe used for the metrics calculation
`payouts_volume`	number	Total payout amount for the specified timeframe
`currency`	string	Currency code for the payout volume (e.g., `"usd"`)

Example Request

curl -X GET "https://api.dots.dev/v2/users/user_abc123/metrics/payouts?timeframe=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "user_id": "user_abc123",
  "timeframe": "last_30_days",
  "payouts_volume": 2500.00,
  "currency": "usd"
}

Error Responses

If you provide an invalid timeframe, the API returns a validation error:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid timeframe. Allowed values: today, this_week, this_month, last_7_days, last_30_days, last_90_days, this_year, all_time"
  }
}

When to Use This Endpoint

Dashboard displays — Show users their total payout history for a given period
Reporting and analytics — Aggregate payout data across users for business intelligence
Compliance audits — Retrieve historical payout totals for a user's records

For app-level metrics (wallet balance, total payouts, connected users), see App Management API. For authentication setup, see Getting Started with the Dots Dashboard.

Was this helpful?