# How to Use CodexBar for Batch Processing Provider Usage Data

> Learn to batch process AI coding provider usage with CodexBar. Aggregate quota data via API calls and view it in a unified interface. Works with steipete/CodexBar.

- Repository: [Peter Steinberger/CodexBar](https://github.com/steipete/CodexBar)
- Tags: how-to-guide
- Published: 2026-07-10

---

**CodexBar does not process barcodes; instead, it aggregates AI-coding provider quota usage through automatic batch API calls (e.g., `?batch=1`), parsing TRPC-shaped responses into a unified menu-bar interface.**

CodexBar is a macOS menu-bar application designed to monitor usage quotas across dozens of AI-coding providers. While the query may suggest barcode processing, the codebase actually implements **batch API processing**—querying provider endpoints that return batched TRPC responses and normalizing them into `UsageSnapshot` models for real-time display.

## Understanding CodexBar's Batch API Architecture

The batch processing workflow centers on the **[`UsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/UsageFetcher.swift)** orchestrator, which delegates to provider-specific implementations. When a provider supports a batch endpoint (indicated by the query parameter `batch=1`), CodexBar automatically constructs the request, parses the batched payload, and presents the data in the menu-bar UI.

The architecture follows a pipeline pattern:

- **[`UsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/UsageFetcher.swift)** – Coordinates high-level fetch operations across all enabled providers, normalizing results into the common `UsageSnapshot` model【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/UsageFetcher.swift】
- **Provider-specific fetchers** – Handle the construction of batch URLs and TRPC response decoding
- **Fallback CLI strategy** – Used when providers lack batch endpoints, configured via [`ProviderCLIConfig.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderCLIConfig.swift)

## How Provider Fetchers Implement Batch Processing

Each supported provider implements its own fetcher class that constructs the batch URL and handles provider-specific authentication.

### KiloUsageFetcher and the batch=1 Parameter

In [`KiloUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/KiloUsageFetcher.swift), the batch request is constructed using `makeBatchURL`, which automatically appends the required query parameter:

```swift
// URLQueryItem construction from KiloUsageFetcher.swift
URLQueryItem(name: "batch", value: "1")

```

The fetcher validates the TRPC response shape—expecting a single-element array containing a `result` object—and throws descriptive `KiloUsageError` cases if the structure is unexpected【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Kilo/KiloUsageFetcher.swift】.

### T3ChatUsageFetcher Implementation

The [`T3ChatUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/T3ChatUsageFetcher.swift) implements similar batch logic for the T3 Chat provider, constructing requests to endpoints like `https://t3.chat/api/trpc/getCustomerData?batch=1&input=ignored` and handling the `x-trpc-batch` header requirements【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/T3Chat/T3ChatUsageFetcher.swift】.

### MistralUsageFetcher Pattern

[`MistralUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/MistralUsageFetcher.swift) follows the same architectural pattern, isolating provider-specific parsing logic while conforming to the batch response protocol【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/Mistral/MistralUsageFetcher.swift】.

## The UsageFetcher Orchestration Layer

The central `UsageFetcher` class manages the refresh loop across all enabled providers. It reads the `pipeline` configuration from [`ProviderDescriptor.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderDescriptor.swift) to determine whether to use batch API fetching or fall back to CLI-based strategies.

When batch mode is active, the fetcher:

1. Invokes `loadLatestUsage()` on each provider's fetcher
2. Receives normalized `UsageSnapshot` objects containing credits remaining, reset countdowns, and incident badges
3. Updates the UI layer without storing passwords—re-using existing API keys, OAuth tokens, or CLI sessions

```swift
// Example: manually invoke a batch fetch for the Kilo provider
import CodexBarCore

let fetcher = KiloUsageFetcher()
Task {
    do {
        // `loadLatestUsage` calls `makeBatchURL` → ?batch=1 automatically
        let snapshot = try await fetcher.loadLatestUsage()
        print("Kilo credits left: \(snapshot.creditsRemaining)")
    } catch {
        print("Failed to fetch Kilo usage: \(error)")
    }
}

```

## Enabling and Configuring Batch Processing

To utilize CodexBar's batch API processing:

1. **Enable the provider** in *Settings → Providers*—the UI automatically selects the batch fetch strategy when available
2. **Authenticate** using existing credentials (API key, OAuth, or CLI session)—CodexBar never stores passwords independently
3. **Run the refresh loop** either via the macOS app or the CLI command:

```bash

# CLI equivalent – fetch all enabled providers in batch mode

codexbar serve --refresh 15s

```

For debugging specific batch endpoints manually:

```bash

# Direct curl of a provider's batch endpoint

curl "https://t3.chat/api/trpc/getCustomerData?batch=1&input=ignored" \
     -H "x-trpc-batch: true"

```

## Error Handling for Batch Responses

Provider fetchers implement strict validation of batch response shapes. The `KiloUsageFetcher` defines specific `KiloUsageError` enums for various failure cases, ensuring that malformed TRPC responses or missing result objects trigger descriptive errors rather than silent failures.

If a provider does **not** expose a batch endpoint, CodexBar transparently falls back to the `KiloCLIFetchStrategy` or equivalent, as defined in the provider descriptor's pipeline configuration【https://github.com/steipete/CodexBar/blob/main/Sources/CodexBarCore/Providers/ProviderDescriptor.swift】.

## Summary

- **CodexBar processes batch API calls**, not barcodes, to aggregate AI provider usage data
- The **[`UsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/UsageFetcher.swift)** orchestrator delegates to provider-specific implementations like [`KiloUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/KiloUsageFetcher.swift), [`T3ChatUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/T3ChatUsageFetcher.swift), and [`MistralUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/MistralUsageFetcher.swift)
- Batch requests automatically append `?batch=1` via `makeBatchURL` and parse TRPC-shaped responses
- Providers without batch support fall back to CLI-based strategies configured in [`ProviderCLIConfig.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderCLIConfig.swift)
- The UI displays normalized `UsageSnapshot` data regardless of whether the source was a batch API, CLI helper, or local file

## Frequently Asked Questions

### Does CodexBar support barcode scanning or processing?

No. Despite potential naming confusion, CodexBar does not handle barcodes. The application aggregates quota usage statistics from AI-coding providers through HTTP API calls, specifically batch TRPC endpoints that use the `batch=1` query parameter.

### What is the batch=1 parameter in CodexBar API calls?

The `batch=1` parameter indicates a TRPC batch endpoint that returns aggregated data in a specific shape (typically a single-element array containing a result object). CodexBar automatically appends this via `URLQueryItem` in provider fetchers like [`KiloUsageFetcher.swift`](https://github.com/steipete/CodexBar/blob/main/KiloUsageFetcher.swift) to retrieve usage statistics in a single request.

### How does CodexBar handle providers without batch endpoints?

When a provider lacks a batch API, CodexBar falls back to CLI-based fetching strategies. The [`ProviderDescriptor.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderDescriptor.swift) configuration defines the pipeline for each provider, switching between `UsageFetcher` implementations and [`ProviderCLIConfig.swift`](https://github.com/steipete/CodexBar/blob/main/ProviderCLIConfig.swift) settings based on capability detection.

### Can I manually trigger batch API requests for debugging?

Yes. You can use the `codexbar serve` CLI command with a refresh interval, or manually curl the endpoints using the same URLs constructed by the fetchers. For example, T3 Chat batch endpoints accept the `x-trpc-batch: true` header and return JSON arrays containing usage data.