---
title: "Get connector cache statistics"
method: GET
path: "/api/v1/connectors/cache/stats"
tags: ["MCP Connectors"]
---

# Get connector cache statistics

`GET /api/v1/connectors/cache/stats`

## Request

- Base URL: `https://agent.getaxonflow.com`
- URL: `https://agent.getaxonflow.com/api/v1/connectors/cache/stats`
- Auth: one of:
  - HTTP basic
  - API key in header `X-Internal-Service-ID` and API key in header `X-Internal-Service-Token`
- TypeScript: <https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/docs/api/v1/connectors/cache/stats/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns the caller's cached-connector count. **The response is
tenant-scoped** (`platform/agent/connector_refresh_api.go:350-355`):
`cached_connectors` is the authenticated tenant's own count, not the
deployment's.

**The cache-health counters are operator telemetry.** `hits`,
`misses`, `evictions`, `factory_creations`, `factory_failures`,
`connection_errors`, `hit_rate_percent`, `last_eviction` and
`last_factory_create` are deployment-wide figures. They appear here
**only** inside a `deployment` object, and **only** for the
internal-service credential
(`platform/agent/connector_refresh_api.go:356-369`). A tenant caller
must not read their absence as zero — it has no cache-health data on
this surface.

Un-scoped equivalents for five of them are always available to
operators on `/prometheus` as
`axonflow_connector_cache_stats{stat="cached_connectors"|"hits"|"misses"|"evictions"|"hit_rate"}`,
refreshed on every call to this endpoint
(`platform/agent/connector_refresh_api.go:338-342`).
`factory_creations`, `factory_failures`, `connection_errors`,
`last_eviction` and `last_factory_create` have **no** Prometheus
series — the `deployment` block is their only surface.

**Authentication.** Wrapped in `apiAuthMiddleware`
(`platform/agent/connector_refresh_api.go:132`). This route takes no
`{tenant_id}` path segment, so it never returns `403`.

*(Historical note: this route was registered with no auth middleware
at all and served the deployment-wide counters to anonymous callers —
#2883, where the `evictions` delta was an existence oracle for
`(tenant, connector)` pairs. Authenticated and scoped as of #3067.)*

## Response `200`

Cache statistics

- ConnectorCacheStats: Connector cache statistics. Source of truth: `platform/agent/connector_refresh_api.go` (`connectorCacheStatsHandler`, lines 350-369). **Tenant-scoped.** A Basic-auth caller receives exactly four top-level fields — `cached_connectors`, `registry_enabled`, `tenant_id`, `timestamp` — and no cache-health counters at all. The counters live in `deployment`, which is present **only** for the internal-service credential. Before #3067 all of the counters were served flat at the top level to anonymous callers; the flat shape no longer exists on any code path.
  - `tenant_id` string: The authenticated tenant `cached_connectors` is scoped to. For an internal-service caller this is whatever `X-Tenant-ID` was sent, or the synthetic `orchestrator-internal` client id when it was not (`platform/agent/authenticator.go:127-130`).
  - `cached_connectors` integer: The number of connectors cached **for `tenant_id`** (`registry.CountByTenant`), not for the deployment. It is typically `0` for an internal-service caller that sent no `X-Tenant-ID` — read `deployment.cached_connectors` instead.
  - `registry_enabled` boolean: Always `true` when the endpoint answers 200 — a disabled or uninitialized registry returns 503 before this body is built.
  - `timestamp` string, date-time: Server time (UTC) at which the body was built
  - `deployment` object: Deployment-wide operator telemetry. **Present only for the internal-service credential** (`platform/agent/connector_refresh_api.go:356`). Absent for every tenant caller; its absence must not be read as zero. Counter values come from `TenantRegistryStats` (`platform/agent/tenant_connector_registry.go:131-141`).
    - `cached_connectors` integer: Deployment-wide cached-connector count (`registry.Count()`)
    - `hits` integer: Total cache hits, deployment-wide
    - `misses` integer: Total cache misses, deployment-wide
    - `evictions` integer: Total manual evictions, deployment-wide
    - `factory_creations` integer: Successful connector factory creations
    - `factory_failures` integer: Failed connector factory creations
    - `connection_errors` integer: Connector initialization errors
    - `hit_rate_percent` number, double: `hits / (hits + misses) * 100`, deployment-wide; `0` when neither counter has moved (`platform/agent/tenant_connector_registry.go:525-534`).
    - `last_eviction` string, date-time: Timestamp of the last eviction. Serializes as the Go zero time `0001-01-01T00:00:00Z` when nothing has been evicted yet.
    - `last_factory_create` string, date-time: Timestamp of the last factory creation. Serializes as the Go zero time `0001-01-01T00:00:00Z` when no connector has been created yet.

## Other responses

- `401`: No usable credential. Written by the auth middleware as `JSONError` (`platform/agent/auth.go:602`), or — when the middleware admitted the caller but resolved no tenancy — by the handler as `ErrorResponse` (`platform/agent/connector_refresh_api.go:148`).
- `503`: Registry not initialized

---

[API](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api.md) - [All operations](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaxonflow/apis/axonflow-agent-api/revisions/34d30fcb7fa1?raw)