/sys/internal/counters

The /sys/internal/counters endpoints are used to return data about the number of Tokens and Entities in Vault. They return information for the entire cluster.

Entities

This endpoint returns the total number of Entities.

Method	Path
`GET`	`/sys/internal/counters/entities`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/entities

Sample response

{
  "request_id": "75cbaa46-e741-3eba-2be2-325b1ba8f03f",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "counters": {
      "entities": {
        "total": 1
      }
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Tokens

This endpoint returns the total number of Tokens.

Method	Path
`GET`	`/sys/internal/counters/tokens`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/tokens

Sample response

{
  "request_id": "75cbaa46-e741-3eba-2be2-325b1ba8f03f",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "counters": {
      "service_tokens": {
        "total": 1
      }
    }
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Client count

This endpoint returns client activity information for a given billing period, which is represented by the start_time and end_time parameters.

The response contains the total activity for the billing period and the attributions of the total activity against specific components in Vault. This helps in understanding the total activity better by knowing which components in Vault lead to that top-level activity count. First-level of attribution breakdowns are by namespaces and months, under the by_namespaces and months JSON block, respectively.
```
{
   "by_namespace":[],
   "months":[]
}
```

by_namespaces breakdowns provide attributions of each namespace to the total activity count. Mount level attributions further break down these namespaces attributions, wherein information can be found on the attributions of each mount path within a given namespace to the overall activity of the namespace.

{
   "by_namespace":[
      {
         "namespace_id":"root",
         "namespace_path":"",
         "counts":{},
         "mounts":[
            {
               "path":"auth/up1/",
               "counts":{}
            },
            {
               "path":"auth/up2/",
               "counts":{}
            }
         ]
      }
   ]
}

months breakdowns provide attributions of each month to the total activity count. These month-level attributions are further broken down into namespace and mount level attributions for each month.

{
   "months":[
      {
         "timestamp":"2021-05-01T00:00:00Z",
         "counts":{},
         "namespaces":[
            {
               "namespace_id":"root",
               "namespace_path":"",
               "counts":{},
               "mounts":[
                  {
                     "path":"auth/up2/",
                     "counts":{}
                  },
                  {
                     "path":"auth/up1/",
                     "counts":{}
                  }
               ]
            },
            {
               "namespace_id":"s07UR",
               "namespace_path":"ns1/",
               "counts":{},
               "mounts":[
                  {
                     "path":"auth/up1/",
                     "counts":{}
                  },
                  {
                     "path":"auth/up2/",
                     "counts":{}
                  }
               ]
            }
         ],
         "new_clients":{}
      }
   ],
}

Each entry in the months breakdown contains a new_clients block. When a token is first used within a billing period, it is considered a new client for that billing period. This means that all the active clients in the first month of the billing period will be considered new clients for that billing period. While these tokens could be generated and counted in the previous billing period, they are still considered new clients in the context of the given billing period. For each subsequent month in the same billing period, the tokens used in those months that were unused in previous months of the same billing period are considered new clients for that month. Hence, the computation of new clients differs for each combination of start_time and end_time.

The new_clients block within the months breakdown will also be further broken down by namespaces and mounts for visibility into which components in Vault lead to the new clients for each month.

{
   "months":[
      {
         "new_clients":{
            "counts":{},
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{},
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{}
                     },
                     {
                        "path":"auth/up1/",
                        "counts":{}
                     }
                  ]
               }
            ]
         }
      }
   ],
}

The response includes month data for the entire queried period, but may not exactly match the start_time and end_time returned in the response. The start_time in the response is the earliest time there is activity data in the queried period. The end_time is the end of the final month of the queried period.
If the end_date supplied to the API is the current month, exact activity information will be returned for all months in the queried period, except for the current month. The last element in the months response stanza will signify the current month. Furthermore, the new_clients counts returned for the current month will be an estimate.

The following is an example of the months breakdown with just the current month information.

The default billing start date used in queries and license utilization reporting will be automatically adjusted to the latest billing year. Past year billing information will still be retained.

For example, assume a customer has signed a deal for 3 years with a license start date of Dec 1, 2023. After upgrading to the version with this change, the billing start date auto-rolls to the most recent year.

If the upgrade happens on Sept 1, 2024, the billing start date will continue to be Dec 1, 2023. Once we reach Dec 1, 2024, the billing start date will automatically roll to Dec 1, 2024.
If the upgrade happens on Dec 15, 2024, the billing start date should automatically roll to Dec 1, 2024 after upgrade.

{
   "months":[
      {
         "timestamp":"current_month_timestamp",
         "counts":{
            "entity_clients":"exact int value",
            "non_entity_clients":"exact int value",
            "secret_syncs":"exact int value",
            "acme_clients":"exact int value",
            "clients":"exact int value"
         },
         "namespaces": [
               {
                  "namespace_id":"root",
                  "namespace_path":"path",
                  "counts":{
                     "entity_clients":"exact int value",
                     "non_entity_clients":"exact int value",
                     "secret_syncs":"exact int value",
                     "acme_clients":"exact int value",
                     "clients":"exact int value"
                  },
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "entity_clients":"exact int value",
                           "non_entity_clients":"exact int value",
                           "secret_syncs":"exact int value",
                           "acme_clients":"exact int value",
                           "clients":"exact int value"
                        },
                     },
                  ]
               },
         ],
         "new_clients":{
            "counts":{
               "entity_clients":"approx int value",
               "non_entity_clients":"approx int value",
               "secret_syncs":"approx int value",
               "acme_clients":"approx int value",
               "clients":"approx int value"
            },
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{},
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{
                          "entity_clients":"approx int value",
                          "non_entity_clients":"approx int value",
                          "secret_syncs":"approx int value",
                          "acme_clients":"approx int value",
                          "clients":"approx int value"
                         },
                     },
                     {
                        "path":"auth/up1/",
                        "counts":{
                          "entity_clients":"approx int value",
                          "non_entity_clients":"approx int value",
                          "secret_syncs":"approx int value",
                          "acme_clients":"approx int value",
                          "clients":"approx int value"
                        }
                     }
                  ]
               }
            ]
         }
      }
   ],
}

Refer to the client count concepts page for more information on how clients map to these client IDs and how they are counted, or for more information about how the new clients for the current month are estimated in a billing period.

The response will include all child namespaces of the namespace in which the request was made. If some namespace has subsequently been deleted, its path will be listed as deleted namespace :ID:. Deleted namespaces are reported only for queries in the root namespace because the information about the namespace path is unknown.

Restricted endpoint

The API path can only be called from the root namespace.

Method	Path
`GET`	`/sys/internal/counters/activity`

Parameters

start_time (string, optional) - An RFC3339 timestamp or Unix epoch time. Specifies the start of the period for which client counts will be reported. If no start time is specified, the billing start date will be used. The billing start date automatically rolls over to the latest billing year at the end of the last cycle.
end_time (string, optional) - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period for which client counts will be reported. If no end time is specified, the end of the current month will be used.
limit_namespaces (int, optional) - Controls the total number of by_namespace data returned. This can be used to return the client counts for the specified number of namespaces having highest activity. If no limit_namespaces parameter is specified, client counts for all namespaces in specified usage period is returned.
current_billing_period (bool, optional) - DEPRECATED Uses the builtin billing start timestamp as start_time and the current time as the end_time, returning a response with the current billing period information without having to explicitly provide a start and end time. This parameter is deprecated, as this option is now the default, so no parameter is needed to specify.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity

Sample response

{
   "request_id":"26be5ab9-dcac-9237-ec12-269a8ca647d5",
   "lease_id":"",
   "renewable":false,
   "lease_duration":0,
   "data":{
      "by_namespace":[
         {
            "namespace_id":"root",
            "namespace_path":"",
            "counts":{
               "entity_clients":20,
               "non_entity_clients":10,
               "secret_syncs": 5,
               "acme_clients": 3,
               "clients":38
            },
            "mounts":[
               {
                  "path":"auth/up1/",
                  "counts":{
                     "entity_clients":10,
                     "non_entity_clients":10,
                     "secret_syncs": 0,
                     "acme_clients": 0,
                     "clients":20
                  }
               },
               {
                  "path":"auth/up2/",
                  "counts":{
                     "entity_clients":5,
                     "non_entity_clients":5,
                     "secret_syncs": 0,
                     "acme_clients": 0,
                     "clients":10
                  }
               },
               {
                  "path":"secrets/kv1/",
                  "counts":{
                     "entity_clients":0,
                     "non_entity_clients":0,
                     "secret_syncs":3,
                     "acme_clients": 0,
                     "clients":3
                  }
               },
               {
                  "path":"secrets/kv2/",
                  "counts":{
                     "entity_clients":0,
                     "non_entity_clients":0,
                     "secret_syncs":0,
                     "acme_clients": 0,
                     "clients":2
                  }
               },
               {
                  "path":"secrets/pki/",
                  "counts":{
                     "entity_clients":0,
                     "non_entity_clients":0,
                     "secret_syncs":0,
                     "acme_clients": 3,
                     "clients":3
                  }
               }
            ]
         },
         {
            "namespace_id":"s07UR",
            "namespace_path":"ns1/",
            "counts":{
               "entity_clients":5,
               "non_entity_clients":5,
               "secret_syncs":0,
               "acme_clients":0,
               "clients":10
            },
            "mounts":[
               {
                  "path":"auth/up1/",
                  "counts":{
                     "entity_clients":0,
                     "non_entity_clients":5,
                     "secret_syncs":0,
                     "acme_clients":0,
                     "clients":5
                  }
               },
               {
                  "path":"auth/up2/",
                  "counts":{
                     "entity_clients":5,
                     "non_entity_clients":0,
                     "secret_syncs":0,
                     "acme_clients":0,
                     "clients":5
                  }
               }
            ]
         }
      ],
      "end_time":"2021-05-31T23:59:59Z",
      "months":[
         {
            "timestamp":"2021-05-01T00:00:00Z",
            "counts":{
               "entity_clients":20,
               "non_entity_clients":10,
               "secret_syncs":5,
               "acme_clients":3,
               "clients":38
            },
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{
                     "entity_clients":15,
                     "non_entity_clients":5,
                     "secret_syncs":5,
                     "acme_clients":3,
                     "clients":23
                  },
                  "mounts":[
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "entity_clients":10,
                           "non_entity_clients":5,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":15
                        }
                     },
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "entity_clients":3,
                           "non_entity_clients":2,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":5
                        }
                     },
                     {
                        "path":"secrets/kv1/",
                        "counts":{
                           "entity_clients":0,
                           "non_entity_clients":0,
                           "secret_syncs":3,
                           "acme_clients":0,
                           "clients":3
                        }
                     },
                     {
                        "path":"secrets/kv2/",
                        "counts":{
                           "entity_clients":0,
                           "non_entity_clients":0,
                           "secret_syncs":2,
                           "acme_clients":0,
                           "clients":2
                        }
                     },
                     {
                        "path":"secrets/pki/",
                        "counts":{
                           "entity_clients":0,
                           "non_entity_clients":0,
                           "secret_syncs":0,
                           "acme_clients":3,
                           "clients":3
                        }
                     },
                  ]
               },
               {
                  "namespace_id":"s07UR",
                  "namespace_path":"ns1/",
                  "counts":{
                     "entity_clients":5,
                     "non_entity_clients":5,
                     "secret_syncs":0,
                     "acme_clients":0,
                     "clients":10
                  },
                  "mounts":[
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "entity_clients":0,
                           "non_entity_clients":5,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":5
                        }
                     },
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "entity_clients":5,
                           "non_entity_clients":0,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":5
                        }
                     }
                  ]
               }
            ],
            "new_clients":{
               "counts":{
                  "entity_clients":10,
                  "non_entity_clients":10,
                  "secret_syncs":2,
                  "acme_clients":1,
                  "clients":23
               },
               "namespaces":[
                  {
                     "namespace_id":"root",
                     "namespace_path":"",
                     "counts":{
                        "entity_clients":5,
                        "non_entity_clients":5,
                        "secret_syncs":2,
                        "acme_clients":1,
                        "clients":13
                     },
                     "mounts":[
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":5,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "entity_clients":5,
                              "non_entity_clients":0,
                              "clients":5
                           }
                        },
                        {
                           "path":"secrets/kv1/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":1,
                              "clients":1
                           }
                        },
                        {
                           "path":"secrets/kv2/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":1,
                              "clients":1
                           }
                        },
                        {
                           "path":"secrets/pki/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":0,
                              "acme_clients":1,
                              "clients":1
                           }
                        }
                     ]
                  },
                  {
                     "namespace_id":"s07UR",
                     "namespace_path":"ns1/",
                     "counts":{
                        "entity_clients":5,
                        "non_entity_clients":5,
                        "secret_syncs":0,
                        "acme_clients":0,
                        "clients":10
                     },
                     "mounts":[
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":5,
                              "secret_syncs":0,
                              "acme_clients":0,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "entity_clients":5,
                              "non_entity_clients":0,
                              "secret_syncs":0,
                              "acme_clients":0,
                              "clients":5
                           }
                        }
                     ]
                  }
               ]
            }
         },
         {
            "timestamp":"2021-04-01T00:00:00Z",
            "counts":{
               "entity_clients":5,
               "non_entity_clients":5,
               "secret_syncs":3,
               "acme_clients":1,
               "clients":14
            },
            "namespaces":[
               {
                  "namespace_id":"root",
                  "namespace_path":"",
                  "counts":{
                     "entity_clients":5,
                     "non_entity_clients":5,
                     "secret_syncs":0,
                     "acme_clients":0,
                     "clients":10
                  },
                  "mounts":[
                     {
                        "path":"auth/up1/",
                        "counts":{
                           "entity_clients":0,
                           "non_entity_clients":5,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":5
                        }
                     },
                     {
                        "path":"auth/up2/",
                        "counts":{
                           "entity_clients":5,
                           "non_entity_clients":0,
                           "secret_syncs":0,
                           "acme_clients":0,
                           "clients":5
                        }
                     }
                  ]
               }
            ],
            "new_clients":{
               "counts":{
                  "entity_clients":5,
                  "non_entity_clients":5,
                  "secret_syncs":3,
                  "acme_clients":1,
                  "clients":14
               },
               "namespaces":[
                  {
                     "namespace_id":"root",
                     "namespace_path":"",
                     "counts":{
                        "entity_clients":5,
                        "non_entity_clients":5,
                        "secret_syncs":3,
                        "acme_clients":1,
                        "clients":14
                     },
                     "mounts":[
                        {
                           "path":"auth/up1/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":5,
                              "secret_syncs":0,
                              "acme_clients":0,
                              "clients":5
                           }
                        },
                        {
                           "path":"auth/up2/",
                           "counts":{
                              "entity_clients":5,
                              "non_entity_clients":0,
                              "secret_syncs":0,
                              "acme_clients":0,
                              "clients":5
                           }
                        },
                        {
                           "path":"secrets/kv1/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":2,
                              "acme_clients":0,
                              "clients":2
                           }
                        },
                        {
                           "path":"secrets/kv2/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":1,
                              "acme_clients":0,
                              "clients":1
                           }
                        },
                        {
                           "path":"secrets/pki/",
                           "counts":{
                              "entity_clients":0,
                              "non_entity_clients":0,
                              "secret_syncs":0,
                              "acme_clients":1,
                              "clients":1
                           }
                        }
                     ]
                  }
               ]
            }
         }
      ],
      "start_time":"2021-01-01T00:00:00Z",
      "total":{
         "entity_clients":20,
         "non_entity_clients":20,
         "secret_syncs":5,
         "acme_clients":3,
         "clients":48
      }
   },
   "wrap_info":null,
   "warnings":null,
   "auth":null
}

Sample request

The following example retrieves the client count for a single month.

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2020-06-30T00%3A00%3A00Z&start_time=2020-06-01T00%3A00%3A00Z

Sample request

The following example retrieves the client counts for top 2 namespaces with highest activity for a usage period.

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity?end_time=2020-06-30T00%3A00%3A00Z&start_time=2020-06-01T00%3A00%3A00Z&limit_namespaces=2

Partial month client count

This endpoint returns the client activity in the current month. The response will have activity attributions per namespace, per mount within each namespaces, and new clients information.

The time period is from the start of the current month, up until the time that this request was made.

Note

The client count may be inaccurate in the moments following a Vault reboot, or leadership change. The estimate will stabilize when background loading of client data has completed.

Restricted endpoint

The API path can only be called from the root namespace.

Method	Path
`GET`	`/sys/internal/counters/activity/monthly`

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity/monthly

Sample response

{
  "request_id": "d0d37f90-96ec-28c7-b59c-b53612cbbcad",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "acme_clients": 0,
    "by_namespace": [
      {
        "counts": {
          "acme_clients": 0,
          "clients": 1,
          "entity_clients": 0,
          "non_entity_clients": 1,
          "secret_syncs": 0
        },
        "mounts": [
          {
            "counts": {
              "acme_clients": 0,
              "clients": 1,
              "entity_clients": 0,
              "non_entity_clients": 1,
              "secret_syncs": 0
            },
            "mount_path": "auth_token_0747d59c"
          }
        ],
        "namespace_id": "root",
        "namespace_path": ""
      }
    ],
    "clients": 1,
    "entity_clients": 0,
    "months": [
      {
        "counts": {
          "acme_clients": 0,
          "clients": 1,
          "entity_clients": 0,
          "non_entity_clients": 1,
          "secret_syncs": 0
        },
        "namespaces": [
          {
            "counts": {
              "acme_clients": 0,
              "clients": 1,
              "entity_clients": 0,
              "non_entity_clients": 1,
              "secret_syncs": 0
            },
            "mounts": [
              {
                "counts": {
                  "acme_clients": 0,
                  "clients": 1,
                  "entity_clients": 0,
                  "non_entity_clients": 1,
                  "secret_syncs": 0
                },
                "mount_path": "auth_token_0747d59c"
              }
            ],
            "namespace_id": "root",
            "namespace_path": ""
          }
        ],
        "new_clients": {
          "counts": {
            "acme_clients": 0,
            "clients": 1,
            "entity_clients": 0,
            "non_entity_clients": 1,
            "secret_syncs": 0
          },
          "namespaces": [
            {
              "counts": {
                "acme_clients": 0,
                "clients": 1,
                "entity_clients": 0,
                "non_entity_clients": 1,
                "secret_syncs": 0
              },
              "mounts": [
                {
                  "counts": {
                    "acme_clients": 0,
                    "clients": 1,
                    "entity_clients": 0,
                    "non_entity_clients": 1,
                    "secret_syncs": 0
                  },
                  "mount_path": "auth_token_0747d59c"
                }
              ],
              "namespace_id": "root",
              "namespace_path": ""
            }
          ]
        },
        "timestamp": "2022-04-01T04:00:00Z"
      }
    ],
    "non_entity_clients": 1,
    "secret_syncs": 0
  },
  "warnings": null
}

Update the client count configuration

Restricted endpoint

The API path can only be called from the root namespace.

The /sys/internal/counters/config endpoint is used to configure logging of active clients.

Method	Path
`POST`	`/sys/internal/counters/config`

Parameters

default_report_months (integer: 12) - DEPRECATED The number of months to report if no start_time is specified in a query.
enabled (string: enable, disable, default) - Enable or disable counting of client activity. When set to default, the client counts are enabled on Enterprise builds and disabled on community builds. Disabling the feature during the middle of a month will discard any data recorded for that month, but does not delete previous months.
Note
Enterprise
License utilization cannot be reported if client counting is disabled.
As of 1.16.0, 1.15.6 and 1.14.10, client counting cannot be disabled as manual license utilization reporting is always enabled.
As of 1.14.0, 1.13.4, 1.12.8 and 1.11.12, client counting cannot be disabled when automated license utilization reporting is enabled.
retention_months (integer: 48) - The number of months of history to retain. The minimum is 48 months and the maximum is 60 months.

Any missing parameters are left at their existing value.

Sample payload

{
  "enabled": "enable",
  "retention_months": 54
}

Sample request

$ curl \
    --request POST
    --header "X-Vault-Token: ..." \
    --data @payload.json
    http://127.0.0.1:8200/v1/sys/internal/counters/config

Read the client count configuration

Reading the configuration shows the current settings, as well as a flag as to whether any data can be queried.

Method	Path
`GET`	`/sys/internal/counters/config`

enabled (string) - returns default-enabled or default-disabled if the configuration is default.
queries_available (bool) - indicates whether any usage report is available. This will initially be false until the end of the first calendar month after the feature is enabled.

Sample request

$ curl \
    --request GET
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/sys/internal/counters/config

Sample response

{
  "request_id": "25a94b99-b49a-c4ac-cb7b-5ba0eb390a25",
  "lease_id": "",
  "lease_duration": 0,
  "renewable": false,
  "data": {
    "enabled": "default-enabled",
    "queries_available": true,
    "retention_months": 48,
    "reporting_enabled": false,
    "billing_start_timestamp": "2022-03-01T00:00:00Z",
  },
  "warnings": null
}

Important change to supported versions

As of 1.16.7, 1.17.3 and later, the billing start date automatically rolls over to the latest billing year at the end of the last cycle.

For more information, refer to the upgrade guide for your Vault version:

Activity export

This endpoint returns an export of the clients that had activity within the provided start and end times. The returned set of client information will be deduplicated over the time window and will show the earliest activity logged for each client. The output will be ordered chronologically by month of activity.

Techn preview

This endpoint is currently in tech preview status.

There are a few things to keep in mind while using this API.

The response includes the actual time period covered, which may not exactly match the query parameters due to the month granularity of data or missing months in the requested time range.
If the end_date supplied to the API is for the current month, the activity information returned by this API will include activity for this month, however it may be up to 20 minutes delayed.
This endpoint can be called from all namespaces. The requested namespace will act as a filter. The exported data will include activity for the requested namespace and all of its children.
sudo required – This endpoint requires sudo capability in addition to any path-specific capabilities.

Method	Path
`GET`	`/sys/internal/counters/activity/export`

Parameters

start_time (string, optional) - An RFC3339 timestamp or Unix epoch time. Specifies the start of the period for which client counts will be reported. If no start time is specified, the billing start time will be used.
end_time (string, optional) - An RFC3339 timestamp or Unix epoch time. Specifies the end of the period for which client counts will be reported. If no end time is specified, the end of current month will be used.
format (string, optional) - The desired format of the output file. Allowed values are csv and json. If no format is provided a default of json will be used.

The response will include all child namespaces of the namespace in which the request was made. If some namespace has subsequently been deleted, its path will be listed as deleted namespace :ID:.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/sys/internal/counters/activity/export

Sample JSON response

The entity alias names for userpass in the sample response records below are user-provided. They are system-provided for AWS and Kubernetes based on how the auth backend has been configured. In the case of AWS, an IAM role ID is used but this can be configured via the iam_alias or ec2_alias configuration parameters. In the case of Kubernetes, the entity alias name has been populated with the service account ID though this can be configured via the alias_name_source configuration parameter.

Formatted for readability

The activity records below are pretty-printed to improve readability. The API returns JSON lines and will thus be compacted so that each record consumes a single line.

{
  "entity_name": "admin",
  "entity_alias_name": "admin",
  "local_entity_alias": false,
  "client_id": "3f210722-7210-98e8-1f0d-e6a39ffb29c6",
  "client_type": "entity",
  "namespace_id": "root",
  "namespace_path": "",
  "mount_accessor": "auth_userpass_a005db73",
  "mount_type": "userpass",
  "mount_path": "auth/userpass/",
  "timestamp": "2024-07-10T09:33:51Z",
  "policies": [
    "secret-read",
    "secret-list",
    "secret-write",
    "secret-delete"
  ],
  "entity_metadata": {
    "email_address": "admin@example.com"
  },
  "entity_alias_metadata": {},
  "entity_alias_custom_metadata": {
    "region": "west",
    "group": "san_francisco",
    "contact_email": "admin@example.com"
  },
  "entity_group_ids": [
    "746fbaf9-ffeb-62b9-7f0b-42d79ca0883f"
  ]
}

{
  "entity_name": "",
  "entity_alias_name": "",
  "local_entity_alias": false,
  "client_id": "590198f7-9178-57d6-c345-48746bb438d8",
  "client_type": "non-entity-token",
  "namespace_id": "YWZzu",
  "namespace_path": "ns1/a/",
  "mount_accessor": "auth_ns_token_e3119312",
  "mount_type": "ns_token",
  "mount_path": "auth/token/",
  "timestamp": "2024-07-08T11:35:23Z",
  "policies": [],
  "entity_metadata": {},
  "entity_alias_metadata": {},
  "entity_alias_custom_metadata": {},
  "entity_group_ids": []
}

{
  "entity_name": "jdoe",
  "entity_alias_name": "jdoe",
  "local_entity_alias": false,
  "client_id": "665a54bf-8652-c0c5-8121-40adf0d9786a",
  "client_type": "entity",
  "namespace_id": "wOsmr",
  "namespace_path": "ns1/a",
  "mount_accessor": "auth_ldap_a005db73",
  "mount_type": "ldap",
  "mount_path": "auth/ldap/",
  "timestamp": "2024-07-08T11:47:57Z",
  "policies": [
    "secret-read"
  ],
  "entity_metadata": {},
  "entity_alias_metadata": {},
  "entity_alias_custom_metadata": {
    "contact_email": "jdoe@example.com",
    "region": "east",
    "group": "new_york"
  },
  "entity_group_ids": [
    "9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270"
  ]
}

{
  "entity_name": "jdoe",
  "entity_alias_name": "jdoe",
  "local_entity_alias": false,
  "client_id": "0640a8f0-b315-cc8a-c0c2-713f663774df",
  "client_type": "entity",
  "namespace_id": "oIiGy",
  "namespace_path": "ns1/b",
  "mount_accessor": "auth_userpass_01a6ea85",
  "mount_type": "userpass",
  "mount_path": "auth/userpass/",
  "timestamp": "2024-07-21T14:51:36Z",
  "policies": [
    "secret-read"
  ],
  "entity_metadata": {},
  "entity_alias_metadata": {},
  "entity_alias_custom_metadata": {
    "region": "east",
    "group": "new_york"
  },
  "entity_group_ids": [
    "76a374a1-72fd-30ca-2455-f51dfeaa805e"
  ]
}

{
  "entity_name": "e91fa61e-d53e-4b0a-8fe2-ce813a064caa",
  "entity_alias_name": "bee2d6ea-b873-47bc-9bc3-6f5e16e5c1b3",
  "local_entity_alias": false,
  "client_id": "cc7c504f-8d10-4add-9951-f6a194f188ec",
  "client_type": "entity",
  "namespace_id": "root",
  "namespace_path": "",
  "mount_accessor": "auth_kubernetes_b596406f",
  "mount_type": "kubernetes",
  "mount_path": "auth/kubernetes/",
  "timestamp": "2024-07-10T09:33:51Z",
  "policies": [
    "secret-read"
  ],
  "entity_metadata": {},
  "entity_alias_metadata": {
      "service_account_uid": "bee2d6ea-b873-47bc-9bc3-6f5e16e5c1b3",
      "service_account_name": "vault-auth",
      "service_account_namespace": "default",
      "service_account_secret_name": "vault-auth-token"
  },
  "entity_alias_custom_metadata": {},
  "entity_group_ids": []
}

{
  "entity_name": "55ee5905-0314-485d-85ad-c29dc987a054",
  "entity_alias_name": "admin",
  "local_entity_alias": false,
  "client_id": "cc7c504f-8d10-4add-9951-f6a194f188ec",
  "client_type": "entity",
  "namespace_id": "root",
  "namespace_path": "",
  "mount_accessor": "auth_aws_c223ff01",
  "mount_type": "aws",
  "mount_path": "auth/aws/",
  "timestamp": "2024-07-10T09:33:51Z",
  "policies": [
    "secret-read"
  ],
  "entity_metadata": {},
  "entity_alias_metadata": {},
  "entity_alias_custom_metadata": {},
  "entity_group_ids": []
}

Sample CSV response

Nested fields within the exported records will be flattened into individual CSV columns. Columns for arrays (policies and entity_group_ids) will be named using the field name and underlying index (e.g. policies.0, policies.1). Columns for key-value pairs (entity_metadata, entity_alias_metadata, and entity_alias_custom_metadata) will be named using the field name and underlying key (e.g. entity_metadata.email_address, entity_alias_metadata.region). A flattened field will only be added if at least one record contains it. If a top-level field (e.g. entity_metadata) is not populated in any of the records then there will not be any flattened fields of prefix enttiy_metadata..

entity_name,entity_alias_name,client_id,client_type,local_entity_alias,namespace_id,namespace_path,mount_accessor,mount_path,mount_type,timestamp,entity_alias_custom_metadata.contact_email,entity_alias_custom_metadata.group,entity_alias_custom_metadata.region,entity_metadata.email_address,entity_group_ids.0,policies.0,policies.1,policies.2,policies.4
admin,admin,3f210722-7210-98e8-1f0d-e6a39ffb29c6,entity,false,root,,auth_userpass_a005db73,auth/userpass/,userpass,2024-07-10T09:33:51Z,admin@example.com,san_francisco,west,admin@example.com,746fbaf9-ffeb-62b9-7f0b-42d79ca0883f,secret-read,secret-list,secret-write,secret-delete
,,590198f7-9178-57d6-c345-48746bb438d8,non-entity-token,false,YWZzu,ns1/a/,auth_ns_token_e3119312,auth/token/,ns_token,2024-07-08T11:35:23Z,,,,,,,,,
jdoe,jdoe,665a54bf-8652-c0c5-8121-40adf0d9786a,entity,false,wOsmr,ns1/a,auth_ldap_a005db73,auth/ldap/,ldap,2024-07-08T11:47:57Z,jdoe@example.com,new_york,east,,9f18cd4a-4e64-a2b2-b001-7b6b0dfb1270,secret-read,,,
jdoe,jdoe,0640a8f0-b315-cc8a-c0c2-713f663774df,entity,false,oIiGy,ns1/b,auth_userpass_01a6ea85,auth/userpass/,userpass,2024-07-21T14:51:36Z,,new_york,east,,76a374a1-72fd-30ca-2455-f51dfeaa805e,secret-read,,,