Retrieve and export community logs

When to use this

01Authentication#

Header

Authorization: Bearer <API_KEY>

Permission

readCommunityLogsShown in the dashboard as “Get Community Logs”

Use a Community API key with the readCommunityLogs permission, and keep it on your server. The key decides the community, so never send a communityId; an unknown query key returns 400. Personal API keys are refused with 403.

02Behaviour#

03Request#

Query parameters#

Headers#

curl --request GET \
  --url 'https://api.returning.ai/v1/community-logs?logType=gamification&startDate=2026-09-01T00:00:00Z&endDate=2026-09-30T23:59:59Z&page=1&limit=100' \
  --header 'Authorization: Bearer <API_KEY>'

04Response#

With format=json, a 200 returns one page in data.records. To read everything, start at page=1 and ask for the next page while data.hasNextPage is true. Dates in date and time are UTC (DD/MM/YYYY and HH:MM); the dashboard shows the same entries in your local time zone. Records by logType:

• gamification: id, userId (a number), createdAt, user (display name), email, action, action_details, action_location, roles (role names), xp, currency, date and time. identifier appears when your community has an active identifier field (null when the trader has no value), premiumCurrency when premium currency awards are on, and coinExpiry (TRUE or empty) when coin expiry is on.
• milestone: _id, milestoneId, milestoneName, userId (a string), user, email (- when unknown), identifierValue, action (such as Stage Completed), actionDetails, createdAt, updatedAt, date and time, plus the rewards given: xps, currencies, multiplier, multiplierAwarded, roles and tags (names under add, remove and overwrite), badges and customRewards.
• api: id, name (the operation, or the name you gave a bulk job), receivedAt, apiKeyName, duration (such as 0.70 seconds, or empty), status (Queued, In progress, Complete, Complete with errors, Error or Cancelled), progress (0 to 100 for bulk jobs, otherwise null), statusCode (null when none was recorded) and error.
• miniGames with spin_the_wheel: id, userId (a string), createdAt, user, identifier, email, gameName, roles, date, time, action (such as Spin Earned or Spin Claimed), actionDetails and spinCount.
• miniGames with quiz: the same first ten fields, with createdAt set to when the attempt was completed, plus attemptNumber, score (such as 3/5) and result (Passed, Failed, or Completed for quizzes without a pass mark).

With format=csv, a 200 returns a link instead of records. page and limit are ignored, and the file holds every match:

{
  "meta": { "status": "success", "statusCode": 200 },
  "message": "Get community logs success.",
  "data": {
    "downloadUrl": "https://media-cdn.returning.ai/community-logs/66f000000000000000000010/<fileId>_gamification-logs.csv",
    "fileName": "gamification-logs.csv",
    "fileSizeBytes": 6429,
    "totalRecords": 55
  }
}

The file is UTF-8 with a byte-order mark, so spreadsheet apps open it correctly. Text cells that start with =, +, - or @ get a leading ', so @all reads '@all. With no matches, the file holds the header row only. Treat downloadUrl as confidential and keep it on your server.

CSV columns follow the dashboard's own log exports. The identifier column is headed with your identifier field's name, and the XP and coin columns with your community's unit names:

• gamification: Ref ID (#1 is the oldest row), User, your identifier, Email, Action, Action Details, Action Location, Role, XP Activity, Coins Activity, then Premium Activity and Coin Expiry when those are on, Date, Time.
• milestone: User, your identifier, Email, Milestone Name, Action, Action Details, Rewards, Date, Time. Rewards lists roles, tags and custom rewards by ID.
• api: Request ID, Request received, Received at (UTC), API key name, Duration, Status, Progress (as a percentage), Status code, Error.
• miniGames: Ref ID, User, your identifier, Email, then Action, Action Details and Spin Count for the wheel or Attempt, Score and Result for quizzes, Game Name, Roles, Date, Time.

A CSV export over 10,000 rows or 10 MB, or one that takes too long to build, returns 202 with meta.code EXPORT_ACCEPTED and data.exportId. The file is then prepared in the background, and you download it from Settings > Logs > Export Histories in the dashboard. Only one large export per log type runs at a time.

{
  "meta": {
    "status": "success",
    "statusCode": 200
  },
  "message": "Get community logs success.",
  "data": {
    "communityId": "66f000000000000000000010",
    "logType": "gamification",
    "startDate": "2026-09-01T00:00:00Z",
    "endDate": "2026-09-30T23:59:59Z",
    "filters": {},
    "totalRecords": 55,
    "currentPage": 1,
    "pageSize": 100,
    "totalPages": 1,
    "hasNextPage": false,
    "hasPreviousPage": false,
    "records": [
      {
        "id": "66f000000000000000000301",
        "userId": 3247779,
        "createdAt": "2026-09-20T12:30:00.000Z",
        "user": "Sample Trader",
        "identifier": "<brokerCustomerId>",
        "email": "trader@example.com",
        "action": "Adjusted by admin",
        "action_details": "Added 10 XP",
        "action_location": "User List",
        "roles": ["Gold Tier", "@all"],
        "xp": 10,
        "currency": 0,
        "date": "20/09/2026",
        "time": "12:30"
      }
    ]
  }
}

05Errors#

{
  "status": "fail",
  "code": "VALIDATION_FAILED",
  "message": "Invalid community log request.",
  "detail": {
    "endDate": "endDate must be on or after startDate"
  }
}

06Next step#