Selecting Models and Monitoring Your Usage in Chappie

Chappie gives you programmatic control over which model handles each conversation and live visibility into how much of your usage quota remains. Models are fetched from the server at runtime, so your app always reflects the latest available options rather than a hard-coded list. Usage data arrives both as an on-demand snapshot from the rate-limits endpoint and as a mid-stream event during active responses.

Default Model

The default model is gpt-5.5. ChappieClient.defaultModel exposes this constant if you want to reference it programmatically:

let defaultSlug = ChappieClient.defaultModel  // "gpt-5.5"

Listing Available Models

Call models() to fetch the server’s current model list. The results are sorted by the server-assigned priority field, so the best available model appears first.

let models = try await client.models()
for model in models {
    print(model.displayName, model.slug)
}

Filtering Models

Pass a ChappieModelFilter to narrow the list to models that match your requirements:

let textModels = try await client.models(
    filter: ChappieModelFilter(
        supportedInAPI: true,
        inputModality: "text"
    )
)

ChappieModelFilter accepts any combination of:

Bool?

Include only models the API accepts for ChappieResponseRequest. Set this to true for any model you plan to use with send or stream.

String?

Filter by input modality string, e.g. "text". A model is included if its inputModalities array contains this value.

Bool?

Include only models that support (or don’t support) the web search tool.

Bool?

Include only models that support (or don’t support) parallel tool calls.

String?

Include only models that list the given reasoning effort level in their supportedReasoningLevels array.

Selecting a Model

Change the active model for a client instance at any time. All subsequent turns will use the new model until you change it again.

await client.selectModel("gpt-5.5")
let selected = await client.selectedModel()

selectModel(_:) is @discardableResult — it returns the new ChappieClientContext snapshot, but you can ignore it if you only need the side effect.

Best Available and Fallback Helpers

Two convenience methods resolve a model from the live list without you having to iterate manually:

// First API-accessible text model, sorted by priority
let best = try await client.bestAvailableModel()

// The preferred slug if available, otherwise the first result
let fallback = try await client.fallbackModel(preferred: "gpt-5.5")

Both methods default to filtering for supportedInAPI: true and inputModality: "text". Pass a custom ChappieModelFilter to change the criteria.

ChappieModel Properties

Each ChappieModel in the returned array exposes the following properties:

Property	Type	Description
`slug` / `id`	`String`	Model identifier used in API requests. `id` is an alias for `slug`.
`displayName`	`String`	Human-readable name for display in your UI.
`description`	`String?`	Optional longer description of the model’s strengths.
`supportedInAPI`	`Bool`	Whether the model can be used in `ChappieResponseRequest`.
`priority`	`Int`	Server-assigned ranking. Higher values appear first in the sorted list.
`contextWindow`	`Int?`	Maximum context size in tokens, if reported by the server.
`supportedReasoningLevels`	`[String]`	Reasoning effort levels the model accepts (e.g. `["minimal", "low", "medium", "high"]`).
`supportsSearchTool`	`Bool`	Whether the model can use the web search tool.
`supportsParallelToolCalls`	`Bool`	Whether the model can execute multiple tool calls in a single turn.
`inputModalities`	`[String]`	Input types the model accepts, e.g. `["text"]`.

Checking Usage Limits

Call usageLimits() to fetch a live ChappieUsageLimitSnapshot from the rate-limits endpoint:

let usage = try await client.usageLimits()
if let primary = usage.primary {
    print("Used: \(primary.usedPercent)%")
    if let resetsAt = primary.resetsAt {
        print("Resets at: \(resetsAt.formatted())")
    }
}

ChappieUsageLimitSnapshot has three window fields:

primary — ChappieUsageLimitWindow with usedPercent, windowMinutes, and resetsAt.
secondary — An additional window some plans expose (e.g., a monthly cap alongside an hourly cap).
credits — ChappieCreditsSnapshot with hasCredits, unlimited, and balance.

You also receive a .usageLimits(snapshot) event mid-stream during active responses, so you can keep a live counter without an extra network call.

Account and Plan Info

Read account details and the current plan from the locally cached credential:

let account = try client.account()
print(account.plan?.displayName ?? "Unknown")
print(account.email ?? "No email")

To refresh the plan from the server (which calls usageLimits() internally and updates the stored credential):

let refreshed = try await client.refreshAccount()
print(refreshed.plan?.displayName ?? "Unknown")

ChappiePlan Values

Plans are represented by ChappiePlan, a struct with rawValue and displayName properties. The SDK maps the following raw values to display names:

Consumer
Business & Enterprise

`rawValue`	`displayName`
`free`	Free
`go`	Go
`plus`	Plus
`pro`	Pro

`rawValue`	`displayName`
`team`	Team
`business`	Business
`enterprise`	Enterprise
`edu`	Edu

Unknown raw values are title-cased automatically (my_custom_plan → My Custom Plan).

Handling Usage Limit Errors

When a request is rejected because the user has hit their quota, the SDK throws ChappieClientError.usageLimitReached(_:) with a ChappieUsageLimit payload. The payload includes the plan, a reset timestamp, and a human-readable message.

do {
    let reply = try await client.send("Hello")
} catch ChappieClientError.usageLimitReached(let limit) {
    print(limit.plan?.displayName ?? "Unknown plan")
    print(limit.resetsAt as Any)
    print(limit.message as Any)
}

ChappieUsageLimit exposes:

ChappiePlan?

The plan associated with the limit that was reached.

Date?

When the quota window resets. Display this to users so they know how long to wait.

TimeInterval?

The same reset as a countdown in seconds, when available.

String?

A human-readable message from the server describing the limit.

String?

The name of the active limit bucket that was reached (sourced from the x-codex-active-limit response header).

Rate-limit errors on streaming responses are thrown from the for try await loop, not returned as an event. Always wrap streaming iterations in a do/catch and handle ChappieClientError.usageLimitReached alongside your other error cases.

Get Started

Authentication

Core Concepts

Guides

Configuration

Testing & Security

Selecting Models and Monitoring Your Usage in Chappie

Default Model

Listing Available Models

Filtering Models

Selecting a Model

Best Available and Fallback Helpers

ChappieModel Properties

Checking Usage Limits

Account and Plan Info

ChappiePlan Values

Handling Usage Limit Errors

​Default Model

​Listing Available Models

​Filtering Models

​Selecting a Model

​Best Available and Fallback Helpers

​ChappieModel Properties

​Checking Usage Limits

​Account and Plan Info

​ChappiePlan Values

​Handling Usage Limit Errors

Default Model

Listing Available Models

Filtering Models

Selecting a Model

Best Available and Fallback Helpers

ChappieModel Properties

Checking Usage Limits

Account and Plan Info

ChappiePlan Values

Handling Usage Limit Errors