xAI Integration
Connect your xAI account to track Grok model costs in Grafient.
Overview
Grafient connects to your xAI team using the Management API to pull historical usage data. This integration tracks costs for all Grok models (Grok 4, Grok 4 Fast, Grok 2, image generation, etc.) with up to 90 days of historical data.
The xAI integration requires both a Management API key and a Team ID. Regular API keys used for chat completions will not work — the Management API is a separate system with its own keys and base URL.
Prerequisites
Before you begin, make sure you have:
- An xAI team with billing enabled at console.x.ai.
- Team Admin role — only admins can create Management API keys.
- A Grafient account on the Free, Pro, or Ultimate plan.
Permissions and Security
Grafient requires a Management API key with Billing: Read Only permission. This ensures the key can only read usage data and cannot modify billing settings, top up credits, or create API keys.
Grafient only reads the following data:
- Historical usage costs grouped by model and day
- Model description labels (e.g., "Chat grok-4-0709")
Grafient will never modify your billing settings, top up credits, or access any prompt/completion content. Your credentials are encrypted with AES-256-GCM before storage and are never exposed after the initial connection.
When creating the Management Key, select only the Billing: Read Only scope. This follows the principle of least privilege. Do not grant API key management or other scopes unless you have a separate need for them.
Create a Connection
Step 1: Find Your Team ID
- Log in to console.x.ai.
- Click on your team name in the top-left corner of the sidebar.
- Select Settings from the dropdown.
- Your Team ID is displayed on the settings page. It is a UUID string (e.g.,
65c1e471-205f-4566-9c5a-07198bcdf4ce). - Copy it for the next steps.
Step 2: Create a Management API Key
- In the xAI Console, go to Settings > Management Keys (or navigate to Team Settings > Management Keys).
- Click Create Management Key.
- Give it a descriptive name, such as
Grafient Integration. - Under Permissions, enable only Billing: Read Only. Leave all other scopes disabled.
- Click Create and copy the generated key immediately.
Management keys are only shown once at creation time. If you lose the key, you will need to create a new one. Store it securely until you complete the next step.
Step 3: Add the Integration to Grafient
- In Grafient, navigate to the Integrations page from the sidebar.
- Click Add Integration.
- Select xAI as the provider.
- Enter a label to identify this integration (e.g.,
Production — xAI). If left blank, a default label is generated for you. - Paste the Team ID from Step 1 into the Team ID field.
- Paste the Management API key from Step 2 into the API Key field.
- Click Test Connection — a green checkmark confirms the credentials are valid.
- Click Add Integration to save.
What Happens Next
Once you add the integration, Grafient will:
- Validate your credentials against the xAI Usage endpoint.
- Backfill historical costs — up to 30 days on Free, or 90 days on Pro/Ultimate.
- Sync daily via an automated job at 6 AM UTC to pull the previous day's finalized cost data.
Your costs will appear on the Dashboard within a few seconds of the initial sync. You can also click Force Sync on the integration card at any time to pull the latest data.
Data Collected
| Data Point | Description |
|---|---|
| Daily cost (USD) | Total spend per day, broken down by model |
| Model breakdown | Cost attributed to each Grok model (e.g., grok-4-0709, grok-4-fast, grok-2-image-1212) |
The xAI Usage API does not currently expose per-model token counts. Grafient tracks cost data only for xAI integrations. Token-level breakdowns are available for providers that support them (Anthropic, OpenAI).
API Endpoint Used
Grafient calls a single endpoint:
| Endpoint | Purpose |
|---|---|
POST /v1/billing/teams/{team_id}/usage | Historical usage data grouped by model description, with daily granularity |
Supported Models
All models returned by the xAI Usage endpoint are tracked automatically, including:
- Chat: Grok 4, Grok 4 Fast, Grok 2
- Images: grok-2-image-1212
- Reasoning variants: grok-4-fast-non-reasoning
New models are tracked automatically as they appear in the Usage API — no configuration changes needed.
Data Freshness
xAI usage data is typically available within a few hours of API usage. The daily cron sync at 6 AM UTC captures the previous day's data. For more recent visibility, use Force Sync on your integration card.
Troubleshooting
"Test Connection" fails
- Verify key type: You need a Management API key, not a regular API key. Management keys are created under Settings > Management Keys in the xAI Console. Regular API keys (used for chat completions) do not have access to the billing endpoints.
- Check permissions: The Management key must have the Billing: Read Only scope enabled. If you created the key without this scope, create a new one.
- Confirm Team ID: Make sure you copied the full Team ID from the xAI Console settings. It should be a UUID string.
- Check your role: Only Team Admins can create Management API keys and access billing data. Verify your role in the xAI Console under team settings.
No cost data appears after sync
- Check for recent usage: If there has been no API usage in the sync window, there will be no cost data to display.
- Wait for data availability: xAI cost data may take several hours to become available after API calls are made.
- Try Force Sync: Click the refresh icon on your integration card to trigger a manual sync.
Integration shows an error status
- Revoked key: If the Management API key was deleted in the xAI Console, the integration will fail. Remove the integration and add a new one with the updated key.
- Team changes: If the team was deleted or you were removed from the team, the integration will stop working. Verify your team membership in the xAI Console.