Count tokens (Messages)

⚠️

Preview — this feature is being built; the design below is the spec.

POST https://app.syntic.ai/v1/messages/count_tokens

The Messages counterpart of token counting: send a Messages request body and get the input token count without running the model. Free, and validated exactly like the real request.

For how this fits into a full workflow, see Token counting.

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer <key>`: a private inference key (`sk_live_...`). See Authentication.
`Content-Type`	Yes	`application/json`

Body parameters

Parameter	Type	Required	Notes
`model`	string	Yes	The model whose tokenizer to use.
`system`	string or array	No	System instructions.
`messages`	array	Yes	Content-block messages.
`tools`	array	No	Tool definitions.

Response

200 OK, Content-Type: application/json

{
  "object": "token_count",
  "model": "Amara S1.2",
  "input_tokens": 18342,
  "details": {
    "system_tokens": 412,
    "message_tokens": 15210,
    "tool_tokens": 1890,
    "image_tokens": 765,
    "document_tokens": 0
  },
  "context_window": 262144,
  "remaining_tokens": 243802
}

Field	Type	Description
`input_tokens`	integer	What `usage.prompt_tokens` would report for the same request, including the Syntic identity instruction.
`details`	object	Breakdown by source; the parts add up to `input_tokens`.
`context_window`	integer	The model’s context size.
`remaining_tokens`	integer	`context_window` minus `input_tokens`. The reply must fit here.

Examples

curl -sS https://app.syntic.ai/v1/messages/count_tokens \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "model": "Amara S1.2",
      "system": "You are a careful contracts assistant.",
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarise clause 14."
            }
          ]
        }
      ]
    }'

import os
 
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/messages/count_tokens",
    headers={
        "Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}",
    },
    json={
        "model": "Amara S1.2",
        "system": "You are a careful contracts assistant.",
        "messages": [
            {
                "role": "user",
                "content": [
                    {
                        "type": "text",
                        "text": "Summarise clause 14.",
                    },
                ],
            },
        ],
    },
    timeout=60,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{resp.status_code} {data['error']['code']}: {data['error']['message']}")
print(data)

const res = await fetch('https://app.syntic.ai/v1/messages/count_tokens', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "model": "Amara S1.2",
    "system": "You are a careful contracts assistant.",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarise clause 14."
          }
        ]
      }
    ]
  }),
})
const data = await res.json()
if (!res.ok) throw new Error(`${res.status} ${data.error.code}: ${data.error.message}`)
console.log(data)

package main
 
import (
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
 
func main() {
	body := strings.NewReader(`{
  "model": "Amara S1.2",
  "system": "You are a careful contracts assistant.",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarise clause 14."
        }
      ]
    }
  ]
}`)
	req, err := http.NewRequest("POST", "https://app.syntic.ai/v1/messages/count_tokens", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SYNTIC_API_KEY"))
	req.Header.Set("Content-Type", "application/json")
 
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
 
	out, _ := io.ReadAll(resp.Body)
	if resp.StatusCode >= 300 {
		panic(fmt.Sprintf("%d: %s", resp.StatusCode, out))
	}
	fmt.Println(string(out))
}

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
 
public class Example {
    public static void main(String[] args) throws Exception {
        String body = """
            {
              "model": "Amara S1.2",
              "system": "You are a careful contracts assistant.",
              "messages": [
                {
                  "role": "user",
                  "content": [
                    {
                      "type": "text",
                      "text": "Summarise clause 14."
                    }
                  ]
                }
              ]
            }
            """;
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://app.syntic.ai/v1/messages/count_tokens"))
            .header("Authorization", "Bearer " + System.getenv("SYNTIC_API_KEY"))
            .header("Content-Type", "application/json")
            .method("POST", HttpRequest.BodyPublishers.ofString(body))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 300) {
            throw new RuntimeException(response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

using System.Net.Http.Headers;
using System.Text;
 
using var http = new HttpClient();
using var request = new HttpRequestMessage(new HttpMethod("POST"), "https://app.syntic.ai/v1/messages/count_tokens");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("SYNTIC_API_KEY"));
request.Content = new StringContent("""
    {
      "model": "Amara S1.2",
      "system": "You are a careful contracts assistant.",
      "messages": [
        {
          "role": "user",
          "content": [
            {
              "type": "text",
              "text": "Summarise clause 14."
            }
          ]
        }
      ]
    }
    """, Encoding.UTF8, "application/json");
 
using var response = await http.SendAsync(request);
var text = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode) throw new Exception($"{(int)response.StatusCode}: {text}");
Console.WriteLine(text);

<?php
$body = <<<'JSON'
{
  "model": "Amara S1.2",
  "system": "You are a careful contracts assistant.",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarise clause 14."
        }
      ]
    }
  ]
}
JSON;
 
$ch = curl_init('https://app.syntic.ai/v1/messages/count_tokens');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SYNTIC_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
 
if ($status >= 300) {
    throw new RuntimeException("$status: $response");
}
print_r(json_decode($response, true));

require "json"
require "net/http"
require "uri"
 
uri = URI("https://app.syntic.ai/v1/messages/count_tokens")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('SYNTIC_API_KEY')}"
req["Content-Type"] = "application/json"
req.body = <<~'JSON'
  {
    "model": "Amara S1.2",
    "system": "You are a careful contracts assistant.",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "Summarise clause 14."
          }
        ]
      }
    ]
  }
JSON
 
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
raise "#{res.code}: #{res.body}" unless res.is_a?(Net::HTTPSuccess)
puts JSON.pretty_generate(JSON.parse(res.body))

Errors

Errors use the error envelope and carry a request_id. Codes specific to this operation:

Status	`type`	`code`	When
400	`invalid_request_error`	`messages_required`	No messages.
400	`invalid_request_error`	`model_required`	`model` is missing. Counting has no default model.
404	`not_found_error`	`model_not_found`	Unknown model name.
401	`authentication_error`	`invalid_api_key`	The key is missing, unknown, revoked or expired.
429	`rate_limit_error`	`rate_limited`	Too many requests; wait for `Retry-After`. See Rate-limit headers.

Messages Models

Was this page helpful?