---
title: Query usage analytics
url: https://developers.wpengine.com/docs/ai/api/reference/operations/getanalytics/
image: https://developers.wpengine.com/og/docs/ai/api/reference/operations/getanalytics.png
---

# Query usage analytics

GET

/v1/analytics

Select code sample

```php
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('GET', 'https://api.ai.wpengine.com/v1/analytics?start_time=1&bucket_width=10m&auth_method=browser_session&actor_type=anonymous&application=wpe-ai-chatbot', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);


echo $response->getBody();
```

- Current environment

Returns credit consumption and request counts aggregated into time-bucketed slots for a project and time range; the project defaults to the account’s own. Requires account-level Okta authentication.

## Authorizations

- **[bearerAuth](https://developers.wpengine.com/docs/ai/api/reference/#bearerauth)**

## Parameters

### Query Parameters

**project_id**

string

The project to query analytics for. Optional: when omitted, the account’s project is used, and one is created for an account that has none. An account with more than one project uses the one named “Default project”, or its oldest when none has that name.

**start_time**

required

integer format: int64

<= 253370764800

Start of the query window as a Unix timestamp in seconds (inclusive).

**end_time**

integer format: int64

<= 253370764800

End of the query window as a Unix timestamp in seconds (exclusive). Defaults to the current time.

**bucket_width**

string

default: 1d

Allowed values: 10m 1h 1d

Width of each time bucket in the response. Defaults to 1d. Maximum query windows per bucket_width: 10m → 24 hours, 1h → 7 days, 1d → 30 days. The 1d limit is 721 hours so a 30-calendar-day window that spans a daylight saving time change is accepted.

**client_id**

string

<= 64 characters

Filter results to a single registered site, identified by the client_id returned by the sites API. When omitted, all sites are included. Usage with no registered site (console, playground and direct API-key traffic) is reported with an empty client_id and cannot be selected by this filter.

**auth_method**

string

Allowed values: browser_session api_key service_token okta internal_service unknown

Filter results by authentication method. When omitted, all auth methods are included. browser_session: browser-session traffic. api_key: API key traffic. service_token: service-token callers. okta: Okta-authenticated callers. internal_service: internal service-to-service calls. unknown: unclassified auth.

**actor_type**

string

Allowed values: anonymous authenticated service unknown

Filter results by actor type. When omitted, all actor types are included. anonymous: unauthenticated end users. authenticated: logged-in end users. service: service accounts. unknown: actor type not yet determined.

**application**

string

Allowed values: wpe-ai-chatbot wpe-ai-playground power-coworker console-coworker power-connector wpe-agents wpe-kb-sync third_party unknown

Filter results by calling application. When omitted, all applications are included. wpe-ai-chatbot: WP Engine AI Chatbot. wpe-ai-playground: WP Engine AI Playground. power-coworker: WP Engine AI Coworker. console-coworker: WP Engine AI Coworker web app. power-connector: WP Engine AI Connector. wpe-agents: WP Engine Agents. wpe-kb-sync: WP Engine knowledge-base sync. third_party: any other identified caller. unknown: no caller user-agent present.

**group_by**

string

Comma-separated list of dimension columns to group results by. When omitted, results are grouped by model and operation (preserving the default behaviour). Valid values: model, operation, client_id, site_id, auth_method, actor_type, application. site_id groups usage by the stable site identifier, so usage recorded under every client_id a site has used across credential rotation is reported as one series. Example: group_by=client_id,application.

## Responses

### 200

Analytics data for the requested time range

Media typeapplication/json

object

**bucket_width**

required

The bucket width used for the response, echoing the request parameter.

string

Allowed values: 10m 1h 1d

**start**

required

Inclusive start of the response window (UTC).

string format: date-time

**end**

required

Exclusive end of the response window (UTC).

string format: date-time

**totals**

required

object

**credits_nano**

required

Total credits consumed, in exact integer nanocredits (1 credit = 1,000,000,000 nanocredits). Divide by 1,000,000,000 to get credits.

integer format: int64

**request_count**

required

Total number of requests.

integer

**models**

required

Per-model, per-operation breakdown sorted by credits descending. Entries with equal credits are ordered by model, operation, client_id, auth_method, actor_type then application (all ascending), so the order is stable across identical requests.

Array\<object>

object

**model**

required

Model identifier (e.g. “google/gemini-3.5-flash”).

string

**operation**

required

Operation type (e.g. “chat”, “image”).

string

**client_id**

The registered site this row is attributed to. Only present when client_id is included in the group_by parameter, and empty within such a response for usage that has no registered site (console, playground and direct API-key traffic).

string

**site_id**

The stable site this row is attributed to, as returned by the sites API. It does not change when the site’s client credentials rotate, so usage from all of the site’s client_ids is combined. Only present when site_id is included in the group_by parameter, and empty within such a response for usage that cannot be resolved to a site.

string

**auth_method**

Authentication method for this row. Only present when auth_method is included in the group_by parameter.

string

Allowed values: browser_session api_key service_token okta internal_service unknown

**actor_type**

Actor type for this row. Only present when actor_type is included in the group_by parameter.

string

Allowed values: anonymous authenticated service unknown

**application**

Calling application for this row. Only present when application is included in the group_by parameter.

string

Allowed values: wpe-ai-chatbot wpe-ai-playground power-coworker console-coworker power-connector wpe-agents wpe-kb-sync third_party unknown

**credits_nano**

required

Credits consumed, in exact integer nanocredits (1 credit = 1,000,000,000 nanocredits). Divide by 1,000,000,000 to get credits.

integer format: int64

**request_count**

required

Number of requests for this model and operation.

integer

**buckets**

required

Array\<object>

object

**timestamp**

required

Start of this bucket (UTC).

string format: date-time

**credits_nano**

required

Credits consumed in this bucket, in exact integer nanocredits (1 credit = 1,000,000,000 nanocredits). Divide by 1,000,000,000 to get credits.

integer format: int64

**request_count**

required

Number of requests in this bucket.

integer

**models**

required

Array\<object>

object

**model**

required

Model identifier (e.g. “google/gemini-3.5-flash”).

string

**operation**

required

Operation type (e.g. “chat”, “image”).

string

**client_id**

The registered site this row is attributed to. Only present when client_id is included in the group_by parameter, and empty within such a response for usage that has no registered site (console, playground and direct API-key traffic).

string

**site_id**

The stable site this row is attributed to, as returned by the sites API. It does not change when the site’s client credentials rotate, so usage from all of the site’s client_ids is combined. Only present when site_id is included in the group_by parameter, and empty within such a response for usage that cannot be resolved to a site.

string

**auth_method**

Authentication method for this row. Only present when auth_method is included in the group_by parameter.

string

Allowed values: browser_session api_key service_token okta internal_service unknown

**actor_type**

Actor type for this row. Only present when actor_type is included in the group_by parameter.

string

Allowed values: anonymous authenticated service unknown

**application**

Calling application for this row. Only present when application is included in the group_by parameter.

string

Allowed values: wpe-ai-chatbot wpe-ai-playground power-coworker console-coworker power-connector wpe-agents wpe-kb-sync third_party unknown

**credits_nano**

required

Credits consumed, in exact integer nanocredits (1 credit = 1,000,000,000 nanocredits). Divide by 1,000,000,000 to get credits.

integer format: int64

**request_count**

required

Number of requests for this model and operation.

integer

#### Example

```json
{
  "bucket_width": "10m",
  "totals": {
    "credits_nano": 12000000000,
    "models": [
      {
        "model": "google/gemini-3.5-flash",
        "operation": "chat",
        "client_id": "wpe_site_9f2c41",
        "site_id": "site_3kTMd1aK9vQ2bXw7ZpL0sN",
        "auth_method": "browser_session",
        "actor_type": "anonymous",
        "application": "wpe-ai-chatbot",
        "credits_nano": 4230000000
      }
    ]
  },
  "buckets": [
    {
      "credits_nano": 1500000000,
      "models": [
        {
          "model": "google/gemini-3.5-flash",
          "operation": "chat",
          "client_id": "wpe_site_9f2c41",
          "site_id": "site_3kTMd1aK9vQ2bXw7ZpL0sN",
          "auth_method": "browser_session",
          "actor_type": "anonymous",
          "application": "wpe-ai-chatbot",
          "credits_nano": 4230000000
        }
      ]
    }
  ]
}
```

### 400

Invalid request body or parameters. On agent create and update, error type “profile_unavailable” means the requested profile is not available to the caller.

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

string

**code**

required

integer

**request_id**

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

#### Example

```json
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 401

Missing or invalid bearer token

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

string

**code**

required

integer

**request_id**

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

#### Example

```json
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

#### Headers

**WWW-Authenticate**

string

##### Example

```
Bearer realm="ai-services"
```

### 403

The token is valid, but the request is forbidden. Error type “permission_error” means the token’s scope/permission is insufficient or the authenticated user is not authorized for the target account; “entitlement_required” means the account may not use WP Engine AI, with error_code giving why when known (not_eligible, terms_required, not_enabled or suspended) and portal_url where to fix it; “account_required” means no billing account could be resolved; and “billing_account_pending” means billing isn’t set up for the account yet, usually because its setup after AI was turned on hasn’t finished. Retry shortly. On /v1/chat/completions when content moderation is enabled, and on /v1/sessions/{session_id}/events, error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

string

**code**

required

integer

**request_id**

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

#### Example

```json
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 503

A required dependency is temporarily unavailable. Retry after a short delay with exponential back-off. An entitlement lookup failure uses error type “entitlement_unavailable”. A model without complete rate coverage uses error type “model_unpriced”. A credit balance that can’t be read uses error type “balance_unavailable”.

Media typeapplication/json

object

**error**

required

object

**message**

required

string

**type**

required

string

**error_code**

Stable, machine-readable cause, set by routes that document their codes (the AI readiness and account AI routes, and an entitlement_required refusal, where it is one of not_eligible, terms_required, not_enabled or suspended); absent elsewhere and on errors from shared layers such as authentication. Clients must allow new codes.

string

**portal_url**

Where the customer can resolve the error, set on an entitlement_required refusal that has an error_code when one is configured.

string

**code**

required

integer

**request_id**

required

Correlation ID for this request, matching the X-Request-ID response header — a 32-character trace ID behind the load balancer, otherwise a UUID. Quote it in support reports.

string

#### Example

```json
{
  "error": {
    "type": "invalid_request_error",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```