1. Community Logs
Returning.AI
  • Getting Started
  • Users
    • User directory and provisioning
    • Get Users with Filters
      POST
    • Create New User
      POST
    • Get User Data
      POST
    • Manage User Account
      POST
    • Get User Milestones
      POST
    • Update User Data, Identifier, And Roles
      POST
    • Update User XP and Currency
      POST
  • Messaging
    • Agent messaging workflow
    • Get Messages
      GET
    • Send Message
      POST
    • Reply Message
      POST
    • React Message
      POST
    • Upload message images
      POST
  • Gamification
    • Leaderboards
      • Leaderboards
      • List leaderboards with pagination
      • Create a new leaderboard
      • Update an existing leaderboard
      • Get a single leaderboard by ID
      • Delete a leaderboard
    • Streaks & Mini Games
      • Mini-game State and History
      • List user streak logs
      • List mini-game logs by user email
      • Get current mini-game and streak state
      • Update user spin-wheel information
    • Referral
      • Referral Program Integration
      • Get referral programs
      • Get user's referral summary
    • Rolling Data
      • Get Daily Calculation Data
      • Get Rolling Calculation Data
    • Match Predictions
      • Create match prediction
      • List match predictions
      • Get match prediction
      • Patch match prediction
      • Publish match prediction
      • Settle match prediction
      • Get settlement results
      • Void match prediction
      • Bulk update match predictions
      • Get bulk job status
      • Get bulk job results
    • Get tier configuration
      GET
    • Get daily user XP and coin changes
      POST
    • Search user gamification logs
      POST
    • Get user activity stats
      POST
  • Rewards & Redemptions
    • Store catalog to redemptions
    • List redemption orders by custom-field identifier
      POST
    • Update redemption order status or refund
      PUT
    • Create redemption order status
      POST
    • List redemption orders by user email
      POST
    • List redemption statuses
      POST
    • Get redemption status by ID
      POST
    • List redemption orders by community
      POST
    • Get redemption order status history
      POST
  • Chart Analysis
    • Create Analysis
    • Get Analysis
    • Update Analysis
    • Delete Analysis
    • List Analyses
    • Append Drawings
  • Bulk Operations
    • Bulk user updates
    • List bulk update jobs
    • Get bulk update job status
    • Get bulk update job details
    • Bulk update users from CSV
    • Bulk update premium currency from CSV
  • Channels
    • Iframe
    • List integration channels
  • Events
    • Outgoing webhooks
      • Encryption
      • User Joins Server
      • User Visits server
      • New Message Posted Anywhere
      • New Message Posted To channel
      • Purchased Store Item
    • Incoming webhooks
      • API Keys & Encryption
      • Send message into channels
      • Update Custom User Fields
      • Update In-game currency
  • Widgets
    • Authenticated Widgets
    • Public widgets
    • Channels
    • Leaderboard
    • Milestone
    • Socials
    • Store
  • Community Analytics
    • Get Loyalty Overview
    • Get Phone Verification Contacts
  • Store
    • Store catalog
    • Purchase History
      • Archive or restore an order
      • Update redemption instructions or voucher details
    • Categories
      • List Store categories
      • Create Store category
      • Get Store category by ID
      • Update Store category
      • Delete Store category
    • Products
      • List products
      • Update products in bulk
      • Create products in bulk
      • Create product with vouchers
      • Read product
      • Update product and append vouchers
      • Delete product
    • Redemption-transaction
      • Get redemption transaction detail
    • Get Store configuration
    • Update Store configuration
  • Community
    • Community directory and appearance
    • Appearance
      • Update community theme colors
      • Update community bot profile
      • Update community URL metadata
      • Update community name and URL
    • Community Users
      • Get community users
      • Get user
    • Create community
  • API Keys
    • API key lifecycle
    • Community API Keys
      • Create API key
      • Read API keys
      • Delete API key
      • Update API key
    • User API Keys
      • List user API keys
      • Create user API key
      • Update user API key
      • Delete user API key
      • Get current API key information
  • User Fields
    • User field definitions and history
    • User Field History
      • Get all user field histories in a community
      • Get user field histories for a specific field
      • Get user field histories for a specific user
      • Get user field histories of specific user field and user
      • Update A User Field Value
      • Deprecated Field-First History Write
      • Deprecated Field-First History Read
    • Get A User Field Definition
    • Update A User Field Definition
    • Create A User Field Definition
    • Delete A User Field Definition
    • List User Field Definitions
  • Legacy
    • Servers
      • Create server
      • List servers
      • Update server metadata
    • Bulk Operations
      • Bulk import users from CSV
    • Authentication
      • Secure Auth
      • Register user with password
      • Verify user email
      • Log in user with password
    • Badges
      • List badges
      • Create badge
      • Update badge
      • Delete badge
      • Remove badge from user
      • Award badge to user
    • Messaging
    • Roles & Permissions
      • List server roles
      • Create role
      • Update role
      • Delete role
      • List user roles
      • Add role to user
      • Remove role from user
    • Users
      • Get user
      • Upload user avatar
    • Channels
      • Create channel
      • Update channel
      • Delete channel
    • API Keys
      • List integration API keys
      • Create integration API key
      • Delete integration API key
      • Update integration API key
  • Data Workflows
    • Read event-ingest lifecycle status by trigger and batch ID.
  • Community Logs
    • Retrieve and export community logs
      GET
  1. Community Logs

Retrieve and export community logs

GET
/v1/community-logs

Overview#

Retrieve community logs as paginated JSON or export CSV. Implemented log types: gamification, milestone, api, miniGames, raffles. Other accepted log types return 501.

Authentication#

Send Authorization: Bearer <COMMUNITY_API_KEY> with readCommunityLogs permission. Community is derived from the API key; do not send communityId. Personal API keys are rejected.

Dates and pagination#

Required: logType, startDate, endDate. Dates are inclusive UTC ISO-8601 timestamps ending in Z; endDate must be on or after startDate. No maximum date span. JSON defaults to page=1 and limit=100 (maximum 500), newest first. API logs use receivedAt, wheel and raffle logs createdAt, quiz logs completedAt. Concurrent changes can shift page boundaries.

Shared filters#

All implemented log types support filters[action], filters[location], filters[userId], filters[email], filters[customFieldIdentifier]. Filters intersect; values within an array are alternatives. Each accepts a string or array, up to 100 values of 500 characters. Example: filters[action][]=Create New User. Email is an exact case-insensitive match; userId is the numeric platform user ID. customFieldIdentifier matches the configured community identifier. Unknown filters and nested operators are rejected. Broad identity lookups can return FILTER_TOO_BROAD.

API logs#

logType=api. action matches API name (for example Create New User or Bulk Update Users); location matches request path. Identity filters select recorded request user identities. JSON/CSV fields: id, name, receivedAt, apiKeyName, duration, status, progress, statusCode, error. Missing values are null/empty; progress is numeric in JSON and a percentage in CSV.

Mini Games history#

logType=miniGames. filters[gameType]=spin_the_wheel (default) or quiz. Optional filters[miniGameId] selects one game by Mongo ID. Wheel action examples: Spin Earned, Spin Claimed; location matches game name or channel name. Quiz action is Completed, Passed or Failed; location matches game name.
Wheel columns: Ref ID, User, configured identifier, Email, Action, Action Details, Spin Count, Game Name, Roles, Date, Time. Quiz uses Result and Score instead of wheel action/spin columns. User is a display-name string; roles contain names. API dates/times are UTC; the settings UI may display local timezone.

Raffle logs#

logType=raffles. Optional filters[miniGameId] selects a raffle by its 24-character Mongo ID. Do not send filters[gameType]. All five shared filters are supported. location matches raffle name (exact, case-insensitive). email matches the displayed current profile email, with stored log email fallback.
Actions accept these labels or their codes: Tickets Purchased (raffle-ticket-purchased), Mission Completed (raffle-mission-completed), Mystery Prize Won (raffle-mystery-prize-won), Grand Prize Won (raffle-grand-prize-won), Prize Claimed (raffle-prize-claimed), Updated by Admin (raffle-admin-updated).
JSON fields: id, userId, createdAt, occurredAt, user (display-name string), identifierValue, email, action, actionDetails, awardSummary, raffleName, ticketCount, ticketCodes, roles (names), date, time. CSV follows the raffle table columns and includes all ticket codes. Dates/times are UTC.

CSV response#

format=csv exports all matches regardless of page/limit. HTTP 200 returns application/json with data.downloadUrl (CDN URL), fileName, fileSizeBytes and totalRecords. Download the URL to obtain CSV; the API does not return raw CSV or raw S3 URLs. Files use UTF-8 BOM, escaped cells and formula protection; empty results contain headers.

Large exports#

Exports exceeding the inline row/byte/time budget reuse the asynchronous Export Histories workflow and return HTTP 202 with a readable message and export history metadata. Check Export Histories for completion.

Examples#

API JSON: logType=api, startDate=2026-09-01T00:00:00Z, endDate=2026-09-24T23:59:59Z, format=json, page=1, limit=100.
Wheel CSV: same dates, logType=miniGames, format=csv, filters[gameType]=spin_the_wheel.
Quiz JSON: logType=miniGames, startDate=2023-09-01T00:00:00Z, endDate=2026-09-24T23:59:59Z, format=json, filters[gameType]=quiz.
Raffle JSON: logType=raffles, startDate=2026-09-01T00:00:00Z, endDate=2026-09-28T23:59:59Z, format=json, page=1, limit=100.
Raffle CSV: same selection with format=csv; HTTP 200 returns a CDN download URL, or HTTP 202 queues a Raffle Logs export.
See saved API cases for executable requests and recorded responses.

Errors#

400: invalid query/filter or FILTER_TOO_BROAD. 401/403: authentication, permission or community access failure. 501: accepted but unimplemented log type. 503: query timeout or unable to confirm export handoff. Service errors include meta.code and detail.

Request

Authorization
or
Query Params

Responses

🟢200
application/json
Bodyapplication/json

🟢202
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --globoff 'https://adss-integration.returning.ai/apis/v1/community-logs?logType=gamification&startDate=2026-09-01T00%3A00%3A00Z&endDate=2026-09-24T23%3A59%3A59Z&format=json&page=1&limit=100&filters[action]=&filters[location]=&filters[userId]=&filters[email]=&filters[customFieldIdentifier]=undefined&filters[gameType]=undefined&filters[miniGameId]=undefined&filters[milestones]=undefined'
Response Response Example
200 - Gamification JSON page
{
    "meta": {
        "status": "success",
        "statusCode": 200
    },
    "message": "Get community logs success.",
    "data": {
        "communityId": "507f1f77bcf86cd799439011",
        "logType": "gamification",
        "startDate": "2026-09-01T00:00:00Z",
        "endDate": "2026-09-24T23:59:59Z",
        "filters": {},
        "totalRecords": 1,
        "currentPage": 1,
        "pageSize": 100,
        "totalPages": 1,
        "hasNextPage": false,
        "hasPreviousPage": false,
        "records": [
            {
                "id": "507f1f77bcf86cd799439099",
                "userId": 12345,
                "createdAt": "2026-09-20T12:30:00.000Z",
                "user": "Example Member",
                "email": "member@example.com",
                "action": "Edit",
                "action_details": "Added 10 XP",
                "action_location": "Admin",
                "roles": [
                    "Member"
                ],
                "xp": 10,
                "currency": 0,
                "date": "20/09/2026",
                "time": "12:30"
            }
        ]
    }
}
Modified at 2026-09-30 04:22:05
Previous
Read event-ingest lifecycle status by trigger and batch ID.
Built with