> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galxe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Space API Reference

> Query space information and loyalty points rankings

## Overview

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

## Core Queries

### Get Space Information

```graphql theme={null}
query GetSpace($spaceId: Int!) {
  space(id: $spaceId) {
    id
    name
    description
  }
}
```

### Get Loyalty Points Rankings

```graphql theme={null}
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**:

```json theme={null}
{
  "spaceId": 40,
  "cursorAfter": null,
  "sprintId": null
}
```

### Alternative: Direct Rankings Query

```graphql theme={null}
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

| Field                | Type                 | Description               |
| -------------------- | -------------------- | ------------------------- |
| `id`                 | `String!`            | Space's unique identifier |
| `name`               | `String!`            | Space display name        |
| `description`        | `String`             | Space description         |
| `loyaltyPointsRanks` | `LoyaltyPointsRanks` | Leaderboard data          |

### Pagination Parameters

| Parameter      | Status        | Description                         |
| -------------- | ------------- | ----------------------------------- |
| `cursorAfter`  | ✅ Current     | Start pagination after this cursor  |
| `cursorBefore` | ✅ Current     | Start pagination before this cursor |
| `sprintId`     | Optional      | Filter by specific sprint           |
| `first`        | ⚠️ Deprecated | Use cursor-based pagination         |
| `after`        | ⚠️ Deprecated | Use cursor-based pagination         |

### LoyaltyPointsRank Fields

| Field     | Type      | Description                    |
| --------- | --------- | ------------------------------ |
| `rank`    | `Int!`    | User's position in leaderboard |
| `points`  | `Int!`    | User's total loyalty points    |
| `address` | `Address` | User profile information       |

## Integration Patterns

### Basic Leaderboard Query

```bash theme={null}
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:

```graphql theme={null}
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

<Warning>
  **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.
</Warning>

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

| Error                 | Cause                | Solution                          |
| --------------------- | -------------------- | --------------------------------- |
| `Space not found`     | Invalid space ID     | Verify space ID exists            |
| `Invalid sprint ID`   | Sprint doesn't exist | Check sprint ID or omit parameter |
| `Rate limit exceeded` | Too many requests    | Implement retry logic             |
| `Invalid cursor`      | Malformed cursor     | Start fresh without cursor        |

## Next Steps

* **[Loyalty Program Guide](/galxe-integration/guides/loyalty-program)** - Points implementation
* **[Leaderboard Guide](/galxe-integration/guides/leaderboards)** - Advanced ranking features
* **[Authentication](/galxe-integration/getting-started/authentication)** - Access token setup