Data & Privacy Architecture

One event is emitted per LLM call. Events are batched and sent to a single endpoint — POST /v1/events/batch — alongside your project ID and API key. That endpoint is the SDK's only network egress. The complete event schema is:

If you group a multi-step run with workflow(), step() or tool(), each event also carries where it sat in that run. Instrument nothing and none of these fields are sent at all:

Calling outcome() adds one more record per run — not per call — carrying only this:

Those three tables are the entire payload. The ids are random and carry no meaning outside your project. The only free text is error, the metadata you attach, and the workflow, step, tool and outcome-label names you write yourself — all documented below.

The SDK intercepts your provider client to read token usage off the response object. It reads the request in memory to count tokens and compute a hash, then discards it. None of the following is transmitted, logged, or stored:

• Prompt and message text
• Model completions and responses
• System prompts and instructions
• Tool definitions, tool arguments, tool results
• Reasoning and thinking blocks
• Skill files, config files, or any file on disk
• Your LLM provider API keys
• Embeddings, documents, or retrieval context

Your provider API keys are a special case: the SDK wraps the client's method, not its credentials. It never reads, stores, or transmits the key you authenticate to OpenAI, Anthropic, or Google with.

No LLM sits in the path of your data on our side either. Optimization recommendations are produced by deterministic analysis over your own usage statistics — there is no model call, and consequently nothing to leak into one.

To detect repeated calls — the signal behind caching recommendations — the SDK needs to know when two prompts are identical, without knowing what they say. It normalizes the request text, takes a SHA-256 digest, and transmits only the digest. The text itself never leaves the function.

# agentcost/anthropic_interceptor.py
def _hash_input(text: str) -> str:
    normalized = " ".join(text.split()).lower().strip()
    return hashlib.sha256(normalized.encode()).hexdigest()

Hashing is one-way: the digest cannot be reversed into the prompt. We want to be precise about the limit of that guarantee, though.

Three things you write can reach us as free text. All are worth understanding before you deploy.

# Good — opaque identifiers
with track_costs.metadata(user_id="u_8fc21a", tenant="acme"):
    llm.invoke(prompt)

# Avoid — personal data in metadata
with track_costs.metadata(email="person@example.com"):
    llm.invoke(prompt)

Pick the one matching your risk tolerance. All three run the same SDK and produce the same analytics.

In local mode the HTTP client is replaced with an in-process stub. No API key is required, no socket is opened, and events stay retrievable in memory:

from agentcost import track_costs

track_costs.init(local_mode=True)

# ... run your agent ...

events = track_costs.get_local_events()   # never left the process

For self-hosting, set AGENTCOST_API_URL (or pass base_url) to your own deployment. The backend is open source and ships with a Dockerfile and compose file.

• AgentCost API keys are stored as SHA-256 digests. The plaintext key is shown once at creation and never persisted, so a database disclosure does not yield usable keys.
• Account passwords are hashed with bcrypt through passlib, with per-password salting and deliberate slowness against offline cracking.
• LLM provider keys are never read by the SDK. It wraps the method on your client object; the credential stays where you configured it.
• Transport is HTTPS to api.agentcost.tech, authenticated with a bearer token scoped to a single project.

While your account is active, usage events are retained indefinitely. This is deliberate: cost trends, baselines, and anomaly detection are only meaningful against long history, and truncating it would silently degrade the product. Events hold no prompt content, so what accumulates is a numeric time series.

Deleting your account starts a 7-day grace period, after which a scheduled job hard-deletes your data. Deletion is explicit rather than reliant on database cascades — the purge removes events, daily aggregates, optimization recommendations, project baselines, input pattern caches, pending invitations, and the projects themselves, then revokes every active session.

Self-hosted deployments set their own retention: the data is in your database and never reaches ours.

Every claim on this page is checkable against source. The SDK and backend are both open source under the MIT license. The files that matter:

• anthropic_interceptor.py — see _build_event for the complete transmitted payload. The OpenAI, Gemini, and LangChain interceptors build the identical shape.
• http_client.py — the only place the SDK opens a socket.
• trace.py — every trace field, and the fact that none are produced outside a workflow().
• tracker.py — local mode swapping the HTTP client for an in-process stub.
• admin_service.py — delete_user_permanently, the deletion path described above.

You can also watch the wire directly. Run your agent against a local proxy, or start in local mode and inspect get_local_events() — the structure is the same one that would have been transmitted.

If you are evaluating AgentCost against a security review and need something this page does not cover, ask. We would rather answer a hard question directly than have you infer the answer.

Email hello@agentcost.tech or open an issue on the SDK repository.