---
title: Count message tokens (Anthropic Messages API)
url: https://developers.wpengine.com/docs/ai/api/reference/operations/countmessagetokens/
image: https://developers.wpengine.com/og/docs/ai/api/reference/operations/countmessagetokens.png
---

# Count message tokens (Anthropic Messages API)

POST

/v1/messages/count_tokens

Select code sample

```php
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/messages/count_tokens', [
  'body' => '{ "model": "anthropic/claude-sonnet-4-6", "messages": [ { "role": "user", "content": "example" } ], "system": "example" }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


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

- Current environment

Counts the input tokens a Messages request would consume, without creating a message or incurring model usage. Accepts the same request shape as /v1/messages minus max_tokens. Authentication matches /v1/messages: a WP Engine bearer token or an “x-api-key” header; API keys must carry the “chat:write” permission. Some models do not support token counting and return a 400 error.

## Authorizations

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

## Request Bodyrequired

Media typeapplication/json

Same shape as an Anthropic Messages request without max_tokens; system and tools are included in the count when supplied.

object

**model**

required

string

### Example

```
anthropic/claude-sonnet-4-6
```

**messages**

required

Array\<object>

object

**role**

required

string

Allowed values: user assistant

**content**

required

Message content: a plain string, or an array of content blocks (text, image, tool_use, tool_result, thinking, …).

**system**

System prompt, as a string or array of content blocks.

## Responses

### 200

Token count for the supplied request

Media typeapplication/json

object

**input_tokens**

required

Tokens the supplied request would consume as input.

integer

#### Example

```json
{
  "input_tokens": 14
}
```

### 400

Invalid request body or parameters, in Anthropic error envelope format (error type “invalid_request_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 401

Missing or invalid credentials, in Anthropic error envelope format (error type “authentication_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

#### Headers

**WWW-Authenticate**

string

##### Example

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

### 403

Valid credentials but insufficient permission, in Anthropic error envelope format (error type “permission_error”). The same type is returned when billing isn’t set up for the account yet, because AI hasn’t been turned on for it in the User Portal or its setup hasn’t finished; the message says so. On /v1/messages, when content moderation is enabled, a 403 with 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

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 404

The requested model was not found or does not support this endpoint, in Anthropic error envelope format (error type “not_found_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 413

Request body exceeds the size limit, in Anthropic error envelope format (error type “request_too_large”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 429

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

Media typetext/html

string

### 502

Upstream provider returned an error, in Anthropic error envelope format (error type “api_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 503

A required dependency (such as the authorization service) is temporarily unavailable, in Anthropic error envelope format (error type “overloaded_error”). Retry after a short delay with exponential back-off.

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### default

Upstream provider error relayed with its original status code and translated into Anthropic error envelope format. The error type reflects the status code (e.g. “rate_limit_error” for 429, “overloaded_error” for 529).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "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"}}]}
```