### Install BattleMetrics

Source: https://context7.com/osesem/battlemetrics/llms.txt

Installation commands for the library via pip from PyPI or GitHub.

```bash
pip install battlemetrics
```

```bash
pip install git+https://github.com/OseSem/battlemetrics
```

--------------------------------

### Get Server Information

Source: https://github.com/osesem/battlemetrics/blob/main/README.md

Basic example to get server information using the Battlemetrics client. Requires an API key.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    client = Battlemetrics("your-api-key")

    # Get server information
    server = await client.get_server(12345)
    print(f"Server: {server.attributes.name}")
    print(f"Players: {server.attributes.players}/{server.attributes.max_players}")

    await client.close()

asyncio.run(main())
```

--------------------------------

### Install BattleMetrics API Wrapper

Source: https://github.com/osesem/battlemetrics/blob/main/README.md

Install the latest published version from PyPI using pip.

```bash
pip install battlemetrics
```

--------------------------------

### Search Players and Get Session History

Source: https://github.com/osesem/battlemetrics/blob/main/README.md

Example using the context manager to search for players by username and game, then retrieve their session history. Requires an API key.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Search for players
        players = await client.list_players(search="username", game="rust")
        for player in players:
            print(f"Player: {player.attributes.name} (ID: {player.id})")

        # Get player session history
        if players:
            sessions = await client.player_session_history(players[0].id)
            for session in sessions:
                print(f"Session: {session.attributes.start} - {session.attributes.stop}")

asyncio.run(main())
```

--------------------------------

### Install Development Version

Source: https://github.com/osesem/battlemetrics/blob/main/README.md

Install the development version from GitHub using pip. Requires Git.

```bash
pip install git+https://github.com/OseSem/battlemetrics
```

--------------------------------

### Search Servers by Criteria

Source: https://github.com/osesem/battlemetrics/blob/main/README.md

Example using the context manager to search for servers based on keywords, game, country, and page size. Requires an API key.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Search for Rust servers in the US
        servers = await client.list_servers(
            search="vanilla",
            game="rust",
            countries=["US"],
            page_size=10
        )
        for server in servers:
            print(f"{server.attributes.name} - {server.attributes.players} players")

asyncio.run(main())
```

--------------------------------

### GET /players/{id}/sessions

Source: https://context7.com/osesem/battlemetrics/llms.txt

Get the session history for a player showing when they played on various servers, including session start/stop times and server details.

```APIDOC
## GET /players/{id}/sessions

### Description
Get the session history for a player showing when they played on various servers, including session start/stop times and server details.

### Method
GET

### Endpoint
/players/{id}/sessions

### Parameters
#### Path Parameters
- **player_id** (integer) - Required - The unique identifier of the player.

#### Query Parameters
- **page_size** (integer) - Optional - Number of results per page.
- **include** (string) - Optional - Relationships to include (e.g., server).
```

--------------------------------

### Get Player Details with Relationships

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieve comprehensive player information, including identifiers and server associations. Use the 'include' parameter to fetch related data.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get player with included relationships
        player = await client.get_player(
            123456789,
            include="identifier,server"
        )

        print(f"Player: {player.attributes.name}")
        print(f"ID: {player.id}")
        print(f"Created: {player.attributes.created_at}")
        print(f"Updated: {player.attributes.updated_at}")

        # Access included data if available
        if player.included:
            for item in player.included:
                print(f"Included: {item.get('type')} - {item.get('id')}")

asyncio.run(main())
```

--------------------------------

### Get Player Session History

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieve a player's session history, including start/stop times and server details. The 'include' parameter can fetch server information for each session.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get player session history
        sessions = await client.player_session_history(
            player_id=123456789,
            page_size=20,
            include="server"
        )

        for session in sessions:
            print(f"Server: {session.attributes.name}")
            print(f"  Start: {session.attributes.start}")
            print(f"  Stop: {session.attributes.stop or 'Still playing'}")
            print(f"  First time: {session.attributes.first_time}")
            print()

asyncio.run(main())
```

--------------------------------

### GET /players/{id}

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieve comprehensive information about a specific player including their identifiers, server associations, and metadata.

```APIDOC
## GET /players/{id}

### Description
Retrieve comprehensive information about a specific player including their identifiers, server associations, and metadata.

### Method
GET

### Endpoint
/players/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique identifier of the player.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of relationships to include (e.g., identifier, server).
```

--------------------------------

### GET /bans

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieve bans with various filters including organization, server, player, and expiration status.

```APIDOC
## GET /bans

### Description
Retrieve bans with various filters including organization, server, player, and expiration status.

### Method
GET

### Endpoint
/bans

### Parameters
#### Query Parameters
- **organization_id** (integer) - Optional - Filter by organization.
- **expired** (boolean) - Optional - Filter by expiration status.
- **page_size** (integer) - Optional - Number of results per page.
- **search** (string) - Optional - Keyword search for bans.
```

--------------------------------

### Get Organization Player Stats

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieves statistics for players within a specific organization, including unique players and identifiers, for a given time range and game. Also demonstrates listing and creating organization friend requests.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get organization player stats
        stats = await client.get_organization_player_stats(
            organization_id=12345,
            range_="AT:2024-01-01T00:00:00Z",
            game="rust"
        )
        print(f"Unique players: {stats.attributes.unique_players}")
        print(f"Identifiers: {stats.attributes.identifiers}")

        # List organization friends
        friends = await client.list_organization_friends(
            organization_id=12345,
            page_size=50
        )
        for friend in friends:
            print(f"Friend: {friend.id}")
            print(f"  Accepted: {friend.attributes.accepted}")
            print(f"  Notes shared: {friend.attributes.notes}")

        # Create organization friend request
        friend_request = await client.create_organization_friend(
            organization_id=12345,
            friend_id=67890,
            identifiers=["steamID"],
            notes=True
        )
        print(f"Friend request: {friend_request.id}")

asyncio.run(main())
```

--------------------------------

### Get Coplay Data for a Player

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieves players who have played with a specific player on servers during overlapping sessions. Requires a player ID and a period for the search.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get coplay data for a player
        coplay = await client.list_coplay(
            player_id=123456789,
            period="AT:2024-01-01T00:00:00Z",
            page_size=50
        )

        print("Players who played with this player:")
        for cp in coplay:
            print(f"  Coplay entry: {cp.id}")

        # Get coplay data for a specific session
        session_coplay = await client.session_coplay(
            session_id="session-id-here",
            page_size=50
        )
        for cp in session_coplay:
            print(f"  Session coplay: {cp.id}")

asyncio.run(main())
```

--------------------------------

### Get Related Identifiers for a Player

Source: https://context7.com/osesem/battlemetrics/llms.txt

Finds related player identifiers such as IP addresses or Steam IDs that may indicate alternate accounts or shared hardware. Specify the player ID and the types of identifiers to match.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get related identifiers for a player
        related = await client.related_identifiers(
            player_id=123456789,
            match_identifiers=["ip", "steamID"],
            page_size=50,
            include="player"
        )

        for rel in related:
            print(f"Related identifier: {rel.attributes.identifier}")
            print(f"  Type: {rel.attributes.type}")
            print(f"  Last seen: {rel.attributes.last_seen}")
            print(f"  Common identifier: {rel.meta.common_identifier}")

asyncio.run(main())
```

--------------------------------

### Initialize BattleMetrics Client

Source: https://context7.com/osesem/battlemetrics/llms.txt

Demonstrates both context manager and manual initialization patterns for the Battlemetrics client.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    # Option 1: Using context manager (recommended)
    async with Battlemetrics("your-api-key") as client:
        server = await client.get_server(12345)
        print(f"Server: {server.attributes.name}")

    # Option 2: Manual initialization and cleanup
    client = Battlemetrics("your-api-key")
    try:
        server = await client.get_server(12345)
        print(f"Server: {server.attributes.name}")
    finally:
        await client.close()

asyncio.run(main())
```

--------------------------------

### Create and List Ban Lists

Source: https://context7.com/osesem/battlemetrics/llms.txt

Create new ban lists with specified actions, organization associations, and default settings. Retrieve a list of all ban lists for the organization or fetch a specific ban list by its ID. Requires an active Battlemetrics client instance.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a new ban list
        banlist = await client.create_banlist(
            name="Cheater Ban List",
            action="kick",  # "none", "log", or "kick"
            organization_id=12345,
            owner_id=67890,
            default_identifiers=["steamID"],
            default_reasons=["Cheating", "Hacking", "Exploiting"],
            default_auto_add_enabled=True,
            default_native_enabled=True
        )
        print(f"Created ban list: {banlist.id}")

        # List all ban lists
        banlists = await client.list_banlists(page_size=50)
        for bl in banlists:
            print(f"Ban List: {bl.id}")

        # Get specific ban list
        banlist = await client.get_banlist("abc123-def456")
        print(f"Ban list name: {banlist.id}")

asyncio.run(main())
```

--------------------------------

### Manage Reserved Slots with Python

Source: https://context7.com/osesem/battlemetrics/llms.txt

Configure VIP reserved slots for players across specific servers. Use these methods to automate slot expiration and server assignment.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a reserved slot
        slot = await client.create_reserved_slot(
            player_id=123456789,
            organization_id=12345,
            server_ids=[67890, 67891],
            expires="2025-12-31T23:59:59Z"
        )
        print(f"Reserved slot created: {slot.id}")

        # List reserved slots
        slots = await client.list_reserved_slots(
            organization_id=12345,
            expired=False,
            page_size=50
        )
        for s in slots:
            print(f"Slot: {s.id}")
            print(f"  Expires: {s.attributes.expires}")

        # Update reserved slot
        updated = await client.update_reserved_slot(
            slot_id="slot-id-here",
            expires="2026-12-31T23:59:59Z",
            server_ids=[67890, 67891, 67892]
        )

        # Delete reserved slot
        await client.delete_reserved_slot(slot_id="slot-id-here")

asyncio.run(main())
```

--------------------------------

### List and Search Servers

Source: https://context7.com/osesem/battlemetrics/llms.txt

Queries servers using filters like game type, country, and status with support for pagination and sorting.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Search for Rust servers in the US
        servers = await client.list_servers(
            search="vanilla",
            game="rust",
            countries=["US"],
            status="online",
            page_size=10,
            sort="-players"  # Sort by player count descending
        )

        for server in servers:
            print(f"{server.attributes.name}")
            print(f"  Players: {server.attributes.players}/{server.attributes.max_players}")
            print(f"  IP: {server.attributes.ip}:{server.attributes.port}")
            print(f"  Rank: {server.attributes.rank}")
            print()

asyncio.run(main())
```

--------------------------------

### Manage Ban List Invites

Source: https://context7.com/osesem/battlemetrics/llms.txt

Create invites to share ban lists, specifying permissions and limits. Accept an invite to subscribe to a shared ban list, configuring its action and organization association. List existing invites for a ban list. Requires an active Battlemetrics client instance.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create an invite for a ban list
        invite = await client.create_banlist_invite(
            banlist_id="abc123-def456",
            limit=10,  # Max organizations that can use this invite
            perm_manage=False,
            perm_create=True,
            perm_update=False,
            perm_delete=False
        )
        print(f"Invite code: {invite.id}")

        # Accept a ban list invite
        subscription = await client.create_banlist_from_invite(
            code="invite-code-here",
            action="kick",
            organization_id=12345,
            owner_id=67890
        )
        print(f"Subscribed to ban list: {subscription.id}")

        # List invites for a ban list
        invites = await client.list_banlist_invites(banlist_id="abc123-def456")
        for inv in invites:
            print(f"Invite: {inv.id}")

asyncio.run(main())
```

--------------------------------

### Manage Servers and RCON Configuration

Source: https://context7.com/osesem/battlemetrics/llms.txt

Handles server registration, metadata updates, and RCON lifecycle management. Ensure the organization ID and server credentials are correct before execution.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a new server
        server = await client.create_server(
            game="rust",
            ip="192.168.1.100",
            port=28015,
            port_query=28016,
            organization_id=12345
        )
        print(f"Server created: {server.id}")

        # Update server configuration
        updated = await client.update_server(
            server_id=int(server.id),
            metadata={"customField": "value"},
            port_query=28017
        )

        # Enable RCON
        rcon_server = await client.enable_server_rcon(
            server_id=int(server.id),
            password="rcon-password",
            port=28016
        )
        print(f"RCON enabled: {rcon_server.attributes.rcon_active}")

        # Connect/disconnect RCON
        await client.connect_server_rcon(server_id=int(server.id))
        await client.disconnect_server_rcon(server_id=int(server.id))

        # Force server update
        refreshed = await client.force_update_server(server_id=int(server.id))

        # Delete RCON configuration
        await client.delete_server_rcon(server_id=int(server.id))

asyncio.run(main())
```

--------------------------------

### Manage Player Notes with Python

Source: https://context7.com/osesem/battlemetrics/llms.txt

Perform CRUD operations on player notes to track organization-specific information. Requires a valid API key and appropriate organization permissions.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a player note
        note = await client.create_player_note(
            player_id=123456789,
            note="Warned for toxic behavior in chat",
            shared=True,  # Visible to organization
            expires_at="2025-06-01T00:00:00Z",
            clearance_level=1,
            organization_id=12345
        )
        print(f"Note created: {note.id}")

        # List player notes
        notes = await client.list_player_notes(
            player_id=123456789,
            expired=False,
            page_size=20
        )
        for n in notes:
            print(f"Note: {n.attributes.note}")
            print(f"  Created: {n.attributes.created_at}")
            print(f"  Shared: {n.attributes.shared}")

        # Update a note
        updated_note = await client.update_player_note(
            player_id=123456789,
            note_id="note-id-here",
            note="Updated: Second warning issued",
            shared=True
        )

        # Delete a note
        await client.delete_player_note(player_id=123456789, note_id="note-id-here")

asyncio.run(main())
```

--------------------------------

### Fetch Server Leaderboards with Python

Source: https://context7.com/osesem/battlemetrics/llms.txt

Access server-specific leaderboards based on metrics like time played. Requires a valid server ID and period definition.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get time-based leaderboard
        leaderboard = await client.get_leaderboard(
            server_id=1234567,
            period="AT:2024-01-01T00:00:00Z",
            leaderboard="time",
            page_size=25
        )

        print("Server Leaderboard (Time Played):")
        for entry in leaderboard:
            print(f"  {entry.id}")

asyncio.run(main())
```

--------------------------------

### Retrieve Server Sessions with Python

Source: https://context7.com/osesem/battlemetrics/llms.txt

Fetch current and historical player activity for a specific server. Filtering by time range allows for detailed session analysis.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Get current sessions on a server
        sessions = await client.server_sessions(
            server_id=1234567,
            include="player"
        )

        print("Current players on server:")
        for session in sessions:
            if session.attributes.stop is None:  # Still active
                print(f"  {session.attributes.name}")
                print(f"    Started: {session.attributes.start}")
                print(f"    First time: {session.attributes.first_time}")

        # Get sessions within a time range
        historical = await client.server_sessions(
            server_id=1234567,
            start="2024-01-01T00:00:00Z",
            stop="2024-01-02T00:00:00Z"
        )
        print(f"Sessions in time range: {len(historical)}")

asyncio.run(main())
```

--------------------------------

### Execute Player Queries

Source: https://context7.com/osesem/battlemetrics/llms.txt

Creates, lists, and runs player-related queries based on custom conditions. Supports both saved queries and ad-hoc custom queries.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a saved player query
        query = await client.create_player_query(
            organization_id=12345,
            query_name="Potential Alt Accounts",
            conditions=[
                {
                    "type": "sharedIP",
                    "value": True
                }
            ]
        )
        print(f"Query created: {query.id}")

        # List saved queries
        queries = await client.list_player_queries(
            organizations=[12345],
            page_size=20
        )
        for q in queries:
            print(f"Query: {q.id}")

        # Run a saved query for a player
        results = await client.run_player_query(
            player_id=123456789,
            query_id="query-id-here",
            page_size=50
        )
        for r in results:
            print(f"Related player: {r.id}")

        # Run a custom query without saving
        custom_results = await client.run_custom_player_query(
            player_id=123456789,
            conditions=[{"type": "sharedIP", "value": True}],
            page_size=50
        )
        for r in custom_results:
            print(f"Custom result: {r.id}")

asyncio.run(main())
```

--------------------------------

### Manage Player Flags

Source: https://context7.com/osesem/battlemetrics/llms.txt

Create custom player flags with names, colors, icons, and descriptions for categorization. Assign flags to players, list all flags, list flags assigned to a specific player, and remove flag assignments. Requires an active Battlemetrics client instance.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Create a player flag
        flag = await client.create_player_flag(
            organization_id=12345,
            name="VIP",
            color="#FFD700",
            icon="star",
            description="VIP players with special privileges"
        )
        print(f"Created flag: {flag.id}")

        # List all flags
        flags = await client.list_player_flags(page_size=50)
        for f in flags:
            print(f"Flag: {f.id}")

        # Assign flag to a player
        assignment = await client.add_player_flag_assignment(
            player_id=123456789,
            player_flag_id="flag-id-here"
        )
        print(f"Flag assigned: {assignment.id}")

        # List flags assigned to a player
        assignments = await client.list_player_flag_assignments(player_id=123456789)
        for a in assignments:
            print(f"Assignment: {a.id}")

        # Remove flag from player
        await client.remove_player_flag_assignment(
            player_id=123456789,
            player_flag_id="flag-id-here"
        )
        print("Flag removed from player")

asyncio.run(main())
```

--------------------------------

### Quick Match Players by Identifier

Source: https://context7.com/osesem/battlemetrics/llms.txt

Quickly match players using their game identifiers like Steam ID or Xbox ID. This endpoint is rate-limited.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Match players by Steam IDs
        identifiers = [
            {"type": "steamID", "identifier": "76561198012345678"},
            {"type": "steamID", "identifier": "76561198087654321"}
        ]

        results = await client.quick_match_players(identifiers)

        for result in results:
            print(f"Identifier: {result.attributes.identifier}")
            print(f"Type: {result.attributes.type}")
            print(f"Last Seen: {result.attributes.last_seen}")
            print(f"Player ID: {result.relationships.player.data.id}")
            print()

asyncio.run(main())
```

--------------------------------

### Handle BattleMetrics API Errors

Source: https://context7.com/osesem/battlemetrics/llms.txt

Demonstrates how to gracefully handle various API errors, including Not Found, Unauthorized, Forbidden, and general HTTP or BattleMetrics exceptions, by using specific exception classes.

```python
import asyncio
from battlemetrics import Battlemetrics
from battlemetrics.errors import (
    BMException,
    HTTPException,
    Unauthorized,
    Forbidden,
    NotFound
)

async def main():
    async with Battlemetrics("your-api-key") as client:
        try:
            player = await client.get_player(999999999)
        except NotFound as e:
            print(f"Player not found: {e.status} - {e.text}")
        except Unauthorized as e:
            print(f"Invalid API key: {e.status} - {e.text}")
        except Forbidden as e:
            print(f"Access denied: {e.status} - {e.text}")
        except HTTPException as e:
            print(f"HTTP error: {e.status} - {e.text}")
            print(f"Response: {e.response}")
        except BMException as e:
            print(f"BattleMetrics error: {e}")

asyncio.run(main())
```

--------------------------------

### List Supported Games and Features

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieves a list of all games supported by BattleMetrics and their associated features. You can also fetch details for a specific game and its features.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # List all supported games
        games = await client.list_games(page_size=50)
        for game in games:
            print(f"Game: {game.id}")

        # Get specific game
        game = await client.get_game("rust")
        print(f"Game details: {game.id}")

        # List game features
        features = await client.list_game_features(game="rust")
        for feature in features:
            print(f"Feature: {feature.id}")

        # List feature options
        options = await client.list_game_feature_options(
            feature_id="feature-id-here",
            page_size=50
        )
        for opt in options:
            print(f"Option: {opt.id}")

asyncio.run(main())
```

--------------------------------

### List Bans with Filters and Search

Source: https://context7.com/osesem/battlemetrics/llms.txt

Retrieve bans using various filters like organization, server, player, and expiration status. Supports keyword search for ban reasons or notes.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # List active bans for an organization
        bans = await client.list_bans(
            organization_id=12345,
            expired=False,
            page_size=50
        )

        for ban in bans:
            print(f"Ban ID: {ban.id}")
            print(f"  Player: {ban.relationships.player.data.id}")
            print(f"  Reason: {ban.attributes.reason}")
            print(f"  Expires: {ban.attributes.expires or 'Permanent'}")
            print(f"  Org Wide: {ban.attributes.org_wide}")
            print()

        # Search bans by keyword
        search_results = await client.list_bans(
            search="cheating",
            organization_id=12345
        )
        print(f"Found {len(search_results)} bans matching 'cheating'")

asyncio.run(main())
```

--------------------------------

### Create a Ban

Source: https://context7.com/osesem/battlemetrics/llms.txt

Create a new ban for a player on your organization's servers. Supports custom reasons, notes, expiration dates, and targeting specific servers or the entire organization.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        ban = await client.create_ban(
            player_id=123456789,
            reason="Cheating - Aimbot detected",
            note="Evidence reviewed by admin team",
            banlist_id="abc123-def456",
            organization_id=12345,
            server_id=67890,
            org_wide=True,  # Ban across all org servers
            auto_add_enabled=True,  # Auto-add new identifiers
            native_enabled=True,  # Enable native game ban
            expires="2025-12-31T23:59:59Z"  # ISO 8601 format, None for permanent
        )

        print(f"Ban created: {ban.id}")
        print(f"UID: {ban.attributes.uid}")
        print(f"Reason: {ban.attributes.reason}")
        print(f"Expires: {ban.attributes.expires or 'Never'}")

asyncio.run(main())
```

--------------------------------

### POST /bans

Source: https://context7.com/osesem/battlemetrics/llms.txt

Create a new ban for a player on your organization's servers. Supports custom reasons, notes, expiration dates, and identifier targeting.

```APIDOC
## POST /bans

### Description
Create a new ban for a player on your organization's servers.

### Method
POST

### Endpoint
/bans

### Request Body
- **player_id** (integer) - Required - The player to ban.
- **reason** (string) - Required - Reason for the ban.
- **note** (string) - Optional - Internal notes.
- **banlist_id** (string) - Optional - The banlist ID.
- **organization_id** (integer) - Optional - The organization ID.
- **server_id** (integer) - Optional - The server ID.
- **org_wide** (boolean) - Optional - Ban across all org servers.
- **auto_add_enabled** (boolean) - Optional - Auto-add new identifiers.
- **native_enabled** (boolean) - Optional - Enable native game ban.
- **expires** (string) - Optional - ISO 8601 expiration date.
```

--------------------------------

### POST /players/match

Source: https://context7.com/osesem/battlemetrics/llms.txt

Quickly match players by their Steam ID, Xbox ID, or other game identifiers. This endpoint is rate limited to 10 requests per second (30 for enterprise).

```APIDOC
## POST /players/match

### Description
Quickly match players by their Steam ID, Xbox ID, or other game identifiers.

### Method
POST

### Endpoint
/players/match

### Request Body
- **identifiers** (array) - Required - List of objects containing 'type' and 'identifier' fields.
```

--------------------------------

### Retrieve Server Information

Source: https://context7.com/osesem/battlemetrics/llms.txt

Fetches detailed attributes for a specific server by ID, including RCON status if available.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        server = await client.get_server(1234567)

        print(f"Server: {server.attributes.name}")
        print(f"Players: {server.attributes.players}/{server.attributes.max_players}")
        print(f"Status: {server.attributes.status}")
        print(f"Country: {server.attributes.country}")
        print(f"IP: {server.attributes.ip}:{server.attributes.port}")
        print(f"Rank: {server.attributes.rank}")

        # Access RCON status if available
        if server.attributes.rcon_active:
            print(f"RCON Status: {server.attributes.rcon_status}")

asyncio.run(main())
```

--------------------------------

### Export Bans in Rust and Arma 3 Formats

Source: https://context7.com/osesem/battlemetrics/llms.txt

Use this snippet to export bans in specific game formats like Rust or Arma 3. Requires an API key and either an organization ID or server ID.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Export bans in Rust format
        rust_bans = await client.export_bans(
            file_format="rust/bans.cfg",
            organization_id=12345
        )
        print("Rust bans exported")

        # Export bans in Arma 3 format
        arma_bans = await client.export_bans(
            file_format="arma3/bans.txt",
            server_id=67890
        )
        print("Arma 3 bans exported")

asyncio.run(main())
```

--------------------------------

### Manage Ban Lists

Source: https://context7.com/osesem/battlemetrics/llms.txt

Endpoints for creating, listing, and retrieving organization ban lists.

```APIDOC
## POST /banlists

### Description
Creates a new ban list for an organization.

### Method
POST

### Endpoint
/banlists

### Request Body
- **name** (string) - Required - Name of the ban list.
- **action** (string) - Required - Action to take (kick, log, none).
- **organization_id** (integer) - Required - ID of the owning organization.
- **owner_id** (integer) - Required - ID of the owner.
- **default_identifiers** (array) - Optional - List of default identifiers.
- **default_reasons** (array) - Optional - List of default reasons.
- **default_auto_add_enabled** (boolean) - Optional - Enable auto-add.
- **default_native_enabled** (boolean) - Optional - Enable native support.

## GET /banlists

### Description
Lists all ban lists accessible to the organization.

### Method
GET

### Endpoint
/banlists

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Number of results per page.
```

--------------------------------

### Retrieve Server Statistics and History

Source: https://context7.com/osesem/battlemetrics/llms.txt

Fetches historical data for player counts, ranks, unique players, and server outages. Requires a valid server ID and ISO 8601 formatted timestamps.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        server_id = 1234567
        start = "2024-01-01T00:00:00Z"
        stop = "2024-01-31T23:59:59Z"

        # Player count history
        player_history = await client.server_player_count_history(
            server_id=server_id,
            start=start,
            stop=stop,
            resolution="60"  # "raw", "30", "60", or "1440"
        )
        print(f"Player count data points: {len(player_history.get('data', []))}")

        # Server rank history
        rank_history = await client.server_rank_history(
            server_id=server_id,
            start=start,
            stop=stop
        )
        print(f"Rank history data points: {len(rank_history.get('data', []))}")

        # Unique player history
        unique_history = await client.server_unique_player_history(
            server_id=server_id,
            start=start,
            stop=stop
        )
        print(f"Unique player data points: {len(unique_history.get('data', []))}")

        # Server outages
        outages = await client.server_outages(
            server_id=server_id,
            range_="AT:2024-01-01T00:00:00Z"
        )
        print(f"Outage records: {len(outages.get('data', []))}")

asyncio.run(main())
```

--------------------------------

### Player Flags

Source: https://context7.com/osesem/battlemetrics/llms.txt

Endpoints to create, assign, and manage custom player flags.

```APIDOC
## POST /player-flags

### Description
Creates a new custom player flag.

### Method
POST

### Endpoint
/player-flags

### Request Body
- **organization_id** (integer) - Required - ID of the organization.
- **name** (string) - Required - Name of the flag.
- **color** (string) - Optional - Hex color code.
- **icon** (string) - Optional - Icon identifier.
- **description** (string) - Optional - Description of the flag.

## POST /players/{player_id}/flags

### Description
Assigns a flag to a player.

### Method
POST

### Endpoint
/players/{player_id}/flags

### Request Body
- **player_flag_id** (string) - Required - The ID of the flag to assign.
```

--------------------------------

### Ban List Invites

Source: https://context7.com/osesem/battlemetrics/llms.txt

Endpoints to manage invitations for sharing ban lists between organizations.

```APIDOC
## POST /banlists/{banlist_id}/invites

### Description
Creates an invite for a specific ban list.

### Method
POST

### Endpoint
/banlists/{banlist_id}/invites

### Request Body
- **limit** (integer) - Optional - Max organizations that can use this invite.
- **perm_manage** (boolean) - Optional - Manage permission.
- **perm_create** (boolean) - Optional - Create permission.
- **perm_update** (boolean) - Optional - Update permission.
- **perm_delete** (boolean) - Optional - Delete permission.

## POST /banlists/invites/accept

### Description
Accepts an invite to subscribe to a ban list.

### Method
POST

### Endpoint
/banlists/invites/accept

### Request Body
- **code** (string) - Required - The invite code.
- **action** (string) - Required - Action to take.
- **organization_id** (integer) - Required - ID of the organization.
- **owner_id** (integer) - Required - ID of the owner.
```

--------------------------------

### Search Players

Source: https://context7.com/osesem/battlemetrics/llms.txt

Searches for players by name with optional filters for game, online status, and pagination.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Search for players by name
        players = await client.list_players(
            search="shroud",
            game="rust",
            page_size=10,
            online=True  # Only online players
        )

        for player in players:
            print(f"Player: {player.attributes.name}")
            print(f"  ID: {player.id}")
            print(f"  Created: {player.attributes.created_at}")
            print(f"  Private: {player.attributes.private}")
            print()

asyncio.run(main())
```

--------------------------------

### Update and Delete Bans

Source: https://context7.com/osesem/battlemetrics/llms.txt

Modify existing bans by updating their reason, notes, expiration, or identifier settings. Remove bans entirely using their ID. Requires an active Battlemetrics client instance.

```python
import asyncio
from battlemetrics import Battlemetrics

async def main():
    async with Battlemetrics("your-api-key") as client:
        # Update a ban
        updated_ban = await client.update_ban(
            ban_id=123456,
            reason="Updated: Confirmed cheating with video evidence",
            note="Appeal denied on 2024-01-15",
            expires=None,  # Make permanent
            org_wide=True
        )
        print(f"Ban updated: {updated_ban.id}")

        # Delete a ban
        await client.delete_ban(ban_id=789012)
        print("Ban deleted successfully")

asyncio.run(main())
```

--------------------------------

### Update and Delete Bans

Source: https://context7.com/osesem/battlemetrics/llms.txt

Endpoints to modify existing ban details or remove a ban from the system.

```APIDOC
## PATCH /bans/{ban_id}

### Description
Updates an existing ban with new reasons, notes, expiration, or identifier settings.

### Method
PATCH

### Endpoint
/bans/{ban_id}

### Parameters
#### Path Parameters
- **ban_id** (integer) - Required - The unique identifier of the ban.

#### Request Body
- **reason** (string) - Optional - The reason for the ban.
- **note** (string) - Optional - Internal notes regarding the ban.
- **expires** (string/null) - Optional - Expiration timestamp or null for permanent.
- **org_wide** (boolean) - Optional - Whether the ban applies organization-wide.

## DELETE /bans/{ban_id}

### Description
Removes a ban from the system.

### Method
DELETE

### Endpoint
/bans/{ban_id}

### Parameters
#### Path Parameters
- **ban_id** (integer) - Required - The unique identifier of the ban.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.