Overview

The Space API provides access to space information and loyalty points leaderboards.

Core Queries

Get Space Information

query GetSpace($spaceId: Int!) {
  space(id: $spaceId) {
    id
    name
    description
  }
}

Get Loyalty Points Rankings

query GetSpaceLeaderboard($spaceId: Int!, $cursorAfter: String, $sprintId: Int) {
  space(id: $spaceId) {
    loyaltyPointsRanks(
      cursorAfter: $cursorAfter
      sprintId: $sprintId
    ) {
      totalCount
      pageInfo {
        hasNextPage
        endCursor
      }
      list {
        rank
        points
        address {
          username
          address
          avatar
        }
      }
    }
  }
}

Variables:

{
  "spaceId": 40,
  "cursorAfter": null,
  "sprintId": null
}

Alternative: Direct Rankings Query

query GetSpaceLoyaltyRanks($spaceId: Int!, $sprintId: Int, $cursorAfter: String) {
  spaceLoyaltyPointsRanks(
    spaceId: $spaceId
    sprintId: $sprintId
    cursorAfter: $cursorAfter
  ) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    list {
      rank
      points
      address {
        username
        address
        avatar
      }
    }
  }
}

Field Reference

Key Fields

FieldTypeDescription
idString!Space’s unique identifier
nameString!Space display name
descriptionStringSpace description
loyaltyPointsRanksLoyaltyPointsRanksLeaderboard data

Pagination Parameters

ParameterStatusDescription
cursorAfter✅ CurrentStart pagination after this cursor
cursorBefore✅ CurrentStart pagination before this cursor
sprintIdOptionalFilter by specific sprint
first⚠️ DeprecatedUse cursor-based pagination
after⚠️ DeprecatedUse cursor-based pagination

LoyaltyPointsRank Fields

FieldTypeDescription
rankInt!User’s position in leaderboard
pointsInt!User’s total loyalty points
addressAddressUser profile information

Integration Patterns

Basic Leaderboard Query

curl -X POST https://graphigo-business.prd.galaxy.eco/query \
  -H "Content-Type: application/json" \
  -H "access-token: YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "query GetLeaderboard($spaceId: Int!) { space(id: $spaceId) { name loyaltyPointsRanks(cursorAfter: null) { totalCount list { rank points address { username } } } } }",
    "variables": { "spaceId": 40 }
  }'

Sprint-Specific Rankings

To get rankings for a specific sprint period, include the sprintId parameter:

loyaltyPointsRanks(sprintId: $sprintId, cursorAfter: $cursorAfter)

Pagination Pattern

  1. Start with cursorAfter: null
  2. Use pageInfo.endCursor from response as next cursorAfter
  3. Continue until pageInfo.hasNextPage is false

User Position Lookup

No Direct User Lookup: The B2B API does not provide a direct user position lookup field like addressLoyaltyPoints. To find a specific user’s rank, you must paginate through the leaderboard pages.

Search Strategy

  1. Limited Search: Search first 10-20 pages for UI responsiveness
  2. Background Search: Comprehensive search for analytics
  3. Cache Results: Store user positions to reduce future searches
  4. Pagination Required: Use cursorAfter/cursorBefore for efficient traversal

Best Practices

  1. Pagination: Use cursor-based pagination (cursorAfter/cursorBefore)
  2. Rate Limiting: Add 200-500ms delays between pagination requests
  3. Caching: Cache leaderboard data for 30-60 seconds
  4. Search Limits: Limit user searches to reasonable page counts (50-100 pages)
  5. Sprint Context: Use sprintId for time-limited competitions

Common Errors

ErrorCauseSolution
Space not foundInvalid space IDVerify space ID exists
Invalid sprint IDSprint doesn’t existCheck sprint ID or omit parameter
Rate limit exceededToo many requestsImplement retry logic
Invalid cursorMalformed cursorStart fresh without cursor

Next Steps