consul/website/content/api-docs/operator/usage.mdx

---
layout: api
page_title: Usage - Operator - HTTP API
description: |-
  The /operator/usage endpoint returns usage information about the number of
  services, service instances and Connect-enabled service instances by
  datacenter.
---

# Usage Operator HTTP API

The `/operator/usage` endpoint returns usage information about the number of
services, service instances and Connect-enabled service instances by datacenter.

| Method | Path              | Produces           |
| ------ | ----------------- | ------------------ |
| `GET`  | `/operator/usage` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/consul/api-docs/features/blocking),
[consistency modes](/consul/api-docs/features/consistency),
[agent caching](/consul/api-docs/features/caching), and
[required ACLs](/consul/api-docs/api-structure#authentication).

| Blocking Queries | Consistency Modes | Agent Caching | ACL Required    |
| ---------------- | ----------------- | ------------- | --------------- |
| `YES`            | `all`             | `none`        | `operator:read` |

The corresponding CLI command is [`consul operator usage instances`](/consul/commands/operator/usage).

### Query Parameters

- `global` `(bool: false)` - If present, usage information for all
  known datacenters will be returned. By default, only the local datacenter's
  usage information is returned.

- `stale` `(bool: false)` - If the cluster does not currently have a leader, an
  error will be returned. You can use the `?stale` query parameter to read the
  Raft configuration from any of the Consul servers.

### Sample Request

```shell-session
$ curl \
    http://127.0.0.1:8500/v1/operator/usage
```

### Sample Response

<Tabs>
<Tab heading="OSS">

```json
{
  "Usage": {
    "dc1": {
      "Services": 1,
      "ServiceInstances": 1,
      "ConnectServiceInstances": {
        "connect-native": 0,
        "connect-proxy": 0,
        "ingress-gateway": 0,
        "mesh-gateway": 0,
        "terminating-gateway": 0
      },
      "BillableServiceInstances": 0
    }
  },
  "Index": 13,
  "LastContact": 0,
  "KnownLeader": true,
  "ConsistencyLevel": "leader",
  "NotModified": false,
  "Backend": 0,
  "ResultsFilteredByACLs": false
}
```

</Tab>
<Tab heading="Enterprise">

```json
{
  "Usage": {
    "dc1": {
      "Services": 1,
      "ServiceInstances": 1,
      "ConnectServiceInstances": {
        "connect-native": 0,
        "connect-proxy": 0,
        "ingress-gateway": 0,
        "mesh-gateway": 0,
        "terminating-gateway": 0
      },
      "BillableServiceInstances": 0,
      "PartitionNamespaceServices": {
        "default": {
          "default": 1
        }
      },
      "PartitionNamespaceServiceInstances": {
        "default": {
          "default": 1
        }
      },
      "PartitionNamespaceBillableServiceInstances": {
        "default": {
          "default": 1
        }
      },
      "PartitionNamespaceConnectServiceInstances": {
        "default": {
          "default": {
            "connect-native": 0,
            "connect-proxy": 0,
            "ingress-gateway": 0,
            "mesh-gateway": 0,
            "terminating-gateway": 0
          }
        }
      }
    }
  },
  "Index": 13,
  "LastContact": 0,
  "KnownLeader": true,
  "ConsistencyLevel": "leader",
  "NotModified": false,
  "Backend": 0,
  "ResultsFilteredByACLs": false
}
```

</Tab>
</Tabs>

- `Services` is the total number of unique service names registered in the
  datacenter.

- `ServiceInstances` is the total number of service instances registered in
  the datacenter.

- `ConnectServiceInstances` is the total number of Connect service instances
  registered in the datacenter.

- `BillableServiceInstances` is the total number of billable service instances
  registered in the datacenter. This is only relevant in Consul Enterprise
  and is the total service instance count, not including any Connect service
  instances or any Consul server instances.

- `PartitionNamespaceServices` <EnterpriseAlert inline /> is the total number
  of unique service names registered in the datacenter, by partition and
  namespace.

- `PartitionNamespaceServiceInstances` <EnterpriseAlert inline /> is the total
  number of service instances registered in the datacenter, by partition and
  namespace.

- `PartitionNamespaceBillableServiceInstances` <EnterpriseAlert inline /> is
  the total number of billable service instances registered in the datacenter,
  by partition and namespace.

- `PartitionNamespaceConnectServiceInstances` <EnterpriseAlert inline /> is
  the total number of Connect service instances registered in the datacenter,
  by partition and namespace.