Returning.AIDevelopers
v1

API reference / Gamification / Rolling Data

.md

Get rolling calculation data

List the rolling totals of your calculated user fields, such as the last 30 days, one row per trader and window.

Last updated 26 Sep 2026API v1

Method
GET
Path
https://api.returning.ai/v1/custom-field-values/rolling
Permission
userFields
Retries
Don't retry the 404

When to use this

  • You show each trader's rolling total for a calculated field, such as trading volume over the last 30 days.
  • You check which traders qualify for a reward based on a rolling window.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
userFieldsShown in the dashboard as “User Fields”

As built, the endpoint takes a Community API key with userFields, shown in the dashboard as User Fields, and the key decides the community. On the public API today, every request gets 404 before the key is checked.

Behaviour#

This endpoint is not available on the public API: https://api.returning.ai/v1/custom-field-values/rolling returns 404 with an empty body for every request. The parameters and the response on this page describe the endpoint as built, and haven't been confirmed on the public API.

Each row is one trader's total of one calculated user field over one window, such as the last 30 days. lastComputedAt says when it was last worked out. Rows are read-only here.

Request#

Query parameters#

fieldId#stringOPTIONAL
Only rows for this user field ID.

Rule24-character hex ID

field_name#stringOPTIONAL
Only rows for this user field key, matched exactly. A key that doesn't exist returns an empty list. Ignored when you send fieldId.

RuleField key

Egtradingvolume

internalName#stringOPTIONAL
Only rows for this calculation, by the name given to it when the field was set up. Matched exactly.

RuleText

timeframe#stringOPTIONAL
Only rows for this window.

Rulelast_30d, last_60d, last_90d, monthly, quarterly, half_yearly or yearly

Eglast_30d

userId#numberOPTIONAL
Only rows for this trader, by platform user ID.

RuleWhole number

Eg3247779

sortBy#stringOPTIONAL
What to sort by.

RulelastComputedAt (default), updatedAt, value or userId

EglastComputedAt

sortOrder#stringOPTIONAL
Sort direction.

Ruledesc (default) or asc

Egdesc

page#numberOPTIONAL
Page number, starting at 1.

RuleWhole number, 1 or more; default 1

Eg1

limit#numberOPTIONAL
Rows per page.

RuleDefault 50; max 200

Eg50

Headers#

Authorization#stringREQUIRED
Community API key with userFields.

RuleBearer <API_KEY>

curl --request GET \
  --url 'https://api.returning.ai/v1/custom-field-values/rolling?field_name=tradingvolume&timeframe=last_30d&limit=50' \
  --header 'Authorization: Bearer <API_KEY>'

Response#

When the path is available, a 200 returns the page in data.data and the totals in data.pagination. Today, expect 404.

status#stringALWAYS
Result of the request.

Rulesuccess

message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The page of rows and the paging totals.
data#object[]ALWAYS
Rows on this page. Empty when nothing matches.
_id#string
The row's ID.
communityId#string
Your community ID.
userId#number
The trader's platform user ID.
email#string
The trader's email, or null when none is stored.
field_name#string
The user field's key, or null when the field no longer exists.
internalName#string
The name given to this calculation when the field was set up.
timeframe#string
The window, such as last_30d.
value#number
The total for the window.
oldestDayInWindow#string
The first day the window covers, ISO 8601.
lastComputedAt#string
When the total was last worked out, ISO 8601 UTC.
createdAt#string
When the row was first written, ISO 8601 UTC.
updatedAt#string
When the row last changed, ISO 8601 UTC.
pagination#objectALWAYS
Paging totals: total, page, limit and totalPages.
{
  "status": "success",
  "message": "Rolling custom field values fetched successfully",
  "data": {
    "data": [
      {
        "_id": "66f000000000000000000731",
        "communityId": "66f000000000000000000010",
        "userId": 3247779,
        "email": "trader@example.com",
        "field_name": "tradingvolume",
        "internalName": "volume_30d",
        "timeframe": "last_30d",
        "value": 1850000,
        "oldestDayInWindow": "2026-08-28T00:00:00.000Z",
        "lastComputedAt": "2026-09-27T00:10:00.000Z",
        "createdAt": "2026-08-01T00:10:00.000Z",
        "updatedAt": "2026-09-27T00:10:00.000Z"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 50,
      "totalPages": 1
    }
  }
}

Errors#

The only response from the public API today is 404 with an empty body.

Do not retry01

404Do not retry
The public API doesn't serve this path yet, so every request returns 404 with an empty body, whatever the key or parameters. Don't retry. Read stored field values with Get a trader's field history instead.
{
  "status": "success",
  "message": "Rolling custom field values fetched successfully",
  "data": {
    "data": [
      {
        "_id": "66f000000000000000000731",
        "communityId": "66f000000000000000000010",
        "userId": 3247779,
        "email": "trader@example.com",
        "field_name": "tradingvolume",
        "internalName": "volume_30d",
        "timeframe": "last_30d",
        "value": 1850000,
        "oldestDayInWindow": "2026-08-28T00:00:00.000Z",
        "lastComputedAt": "2026-09-27T00:10:00.000Z",
        "createdAt": "2026-08-01T00:10:00.000Z",
        "updatedAt": "2026-09-27T00:10:00.000Z"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "limit": 50,
      "totalPages": 1
    }
  }
}

Next step#

Get a trader's field historyGET/v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/historiesRead the stored values of a user field for one trader.