# 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.

- Endpoint: `GET https://api.returning.ai/v1/custom-field-values/rolling`
- Section: Gamification / Rolling data
- Authentication: `Authorization: Bearer <API_KEY>` (Community API key)
- Permission: `userFields` (Shown in the dashboard as "User Fields")
- Retries: Don't retry the 404
- Guide: hand-written
- Verified: code, 2026-09-27
- Last updated: 26 Sep 2026
- Web page: https://docs.returning.ai/api-reference/gamification-rolling-data/get-rolling-calculation-data

## 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.

**Instead:** Use [Get a trader's field history](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-a-traders-field-history.md) instead to read the stored values of one trader's user field.

**Availability:** api.returning.ai doesn't serve this route yet: requests return an empty `404`. Ask Returning.AI before you build on it.

## Authentication

- Header: `Authorization: Bearer <API_KEY>`
- Permission: `userFields`

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `fieldId` | `string` | No | Only rows for this user field ID. (24-character hex ID) |
| `field_name` | `string` | No | Only rows for this user field key, matched exactly. A key that doesn't exist returns an empty list. Ignored when you send `fieldId`. (Field key) |
| `internalName` | `string` | No | Only rows for this calculation, by the name given to it when the field was set up. Matched exactly. (Text) |
| `timeframe` | `string` | No | Only rows for this window. (`last_30d`, `last_60d`, `last_90d`, `monthly`, `quarterly`, `half_yearly` or `yearly`) |
| `userId` | `number` | No | Only rows for this trader, by platform user ID. (Whole number) |
| `sortBy` | `string` | No | What to sort by. (`lastComputedAt` (default), `updatedAt`, `value` or `userId`) |
| `sortOrder` | `string` | No | Sort direction. (`desc` (default) or `asc`) |
| `page` | `number` | No | Page number, starting at 1. (Whole number, 1 or more; default 1) |
| `limit` | `number` | No | Rows per page. (Default 50; max 200) |

### Headers

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `Authorization` | `string` | Yes | Community API key with `userFields`. (`Bearer <API_KEY>`) |

### Example request

```bash
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`.

### Response fields

| Field | Type | Presence | Description |
| --- | --- | --- | --- |
| `status` | `string` | always | Result of the request. (`success`) |
| `message` | `string` | always | Human-readable summary. Do not branch on it. |
| `data` | `object` | always | The page of rows and the paging totals. |
| `data.data` | `object[]` | always | Rows on this page. Empty when nothing matches. |
| `data.data._id` | `string` | - | The row's ID. |
| `data.data.communityId` | `string` | - | Your community ID. |
| `data.data.userId` | `number` | - | The trader's platform user ID. |
| `data.data.email` | `string` | - | The trader's email, or `null` when none is stored. |
| `data.data.field_name` | `string` | - | The user field's key, or `null` when the field no longer exists. |
| `data.data.internalName` | `string` | - | The name given to this calculation when the field was set up. |
| `data.data.timeframe` | `string` | - | The window, such as `last_30d`. |
| `data.data.value` | `number` | - | The total for the window. |
| `data.data.oldestDayInWindow` | `string` | - | The first day the window covers, ISO 8601. |
| `data.data.lastComputedAt` | `string` | - | When the total was last worked out, ISO 8601 UTC. |
| `data.data.createdAt` | `string` | - | When the row was first written, ISO 8601 UTC. |
| `data.data.updatedAt` | `string` | - | When the row last changed, ISO 8601 UTC. |
| `data.pagination` | `object` | always | Paging totals: `total`, `page`, `limit` and `totalPages`. |

### Example response (200)

```json
{
  "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 retry

| Status | Code | What to do |
| --- | --- | --- |
| 404 | - | 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. |

**Retries:** Don't retry the `404`; repeating the request won't make the path available. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry.

## Next step

- [Get a trader's field history](https://docs.returning.ai/api-reference/user-fields-user-field-history/get-a-traders-field-history.md): `GET /v1/communities/{communityId}/users/{userId}/user-fields/{fieldIdOrName}/histories`. Read the stored values of a user field for one trader.
- [See the daily values behind a window with Get daily calculation data](https://docs.returning.ai/api-reference/gamification-rolling-data/get-daily-calculation-data.md): `GET /v1/custom-field-values/daily`.