Developer API

User Payouts Metrics API

The /v2/users/:user_id/metrics/payouts endpoint returns payout volume metrics for a specific user. Use this endpoint to track total money received by a user across different time windows.

Authentication

This endpoint requires both:

  • Session authentication — A valid login session

  • API auth level 2 — Elevated API credentials

Requests without valid authentication receive HTTP 403 with a JSON response:

{
  "success": false
}

GET /v2/users/:user_id/metrics/payouts

Retrieves payout volume metrics for a specific user.

Path Parameters

Parameter

Type

Description

user_id

string

The external ID of the user (from the app connection)

Query Parameters

Parameter

Type

Default

Description

timeframe

string

all_time

The time window for metrics aggregation

Valid timeframe values:

  • 1d — Last 1 day

  • 3d — Last 3 days

  • 1w — Last 1 week

  • 1m — Last 1 month

  • 3m — Last 3 months

  • 1y — Last 1 year

  • all_time — All time (default)

Invalid timeframe values return HTTP 400 with the error: Invalid timeframe: must be one of 1d, 3d, 1w, 1m, 3m, 1y, all_time

Response Fields

Field

Type

Description

user_id

string

The user's external ID from the app connection

timeframe

string

The timeframe used for this response

payouts_volume

number

Total payout volume received by this user in the specified timeframe

currency

string

Currency of the volume value (usd)

Example Request

GET /v2/users/usr_abc123/metrics/payouts?timeframe=1m HTTP/1.1
Host: api.dots.dev
Authorization: Bearer your_api_key

Example Response

{
  "user_id": "usr_abc123",
  "timeframe": "1m",
  "payouts_volume": 2500.00,
  "currency": "usd"
}

Default Behavior

If you omit the timeframe parameter, the endpoint uses all_time by default:

GET /v2/users/usr_abc123/metrics/payouts HTTP/1.1
{
  "user_id": "usr_abc123",
  "timeframe": "all_time",
  "payouts_volume": 15000.00,
  "currency": "usd"
}

Error Responses

Invalid Timeframe (HTTP 400)

{
  "error": "Invalid timeframe: must be one of 1d, 3d, 1w, 1m, 3m, 1y, all_time"
}

Authentication Failure (HTTP 403)

{
  "success": false
}

For app-level metrics including wallet balance and total payouts, see App Management API.

For authentication setup and API key management, see Getting Started with the Dots Dashboard.

Was this helpful?
Was this helpful?