Skip to content

Quick Start

Dhanush edited this page Oct 23, 2026 · 1 revision

Quick Start

This example reads an existing Codex CLI login and prints provider-reported quota windows. No account is accessed until the program calls fetch.

1. Add dependencies

[dependencies]
agentstat = { version = "0.1.0", features = ["local-files"] }
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

2. Add src/main.rs

use agentstat::{Client, ProviderId, local::CredentialLocation};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::builder().allow_local_files(true).build()?;
    let request = client
        .load_local_credentials(ProviderId::Codex, CredentialLocation::Native)
        .await?;
    let snapshot = client.fetch(request).await?;

    for window in &snapshot.windows {
        println!("{}: {:?}% used; resets {:?}",
            window.id, window.utilization_percent, window.resets_at);
    }
    Ok(())
}

3. Run it

cargo run

You need an existing Codex CLI login. agentstat reads its local credential file only because the local-files feature and the runtime opt-in are both present. It does not start a login flow or refresh an expired token.

Try repository examples

From the agentstat checkout:

cargo run --features local-files --example model_usage -- codex
cargo run --features local-files --example real_usage -- codex

The real_usage example also supports Claude, Cursor, Antigravity, OpenCode, and Ollama when you enable the corresponding features and supply their credentials. See Credentials and Accounts and OpenCode Go and Zen.

Supply a token yourself

If you already have a credential for a supported provider, use FetchRequest directly:

use agentstat::{Client, Credentials, FetchRequest, ProviderId};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let token = std::env::var("AGENTSTAT_TOKEN")?;
    let snapshot = Client::builder().build()?.fetch(FetchRequest::new(
        ProviderId::Codex,
        Credentials::bearer(token),
    )).await?;
    println!("{} quota windows", snapshot.windows.len());
    Ok(())
}

Credential type matters: a Codex subscription requires its OAuth token; an OpenAI organization cost report uses an Admin API key and the openai feature. See Provider Coverage before switching the provider ID.

Clone this wiki locally