AALLM Docs

Compare deployments

Filter a candidate set by hard capability requirements, calculate an identical usage profile, and rank compatible deployments by price.

Request

POST/v1/deployments/compareAuthentication: Required
cURL
curl https://api.use-allm.com/v1/deployments/compare \
  -X POST \
  -H "Authorization: Bearer $ALLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "deployment_ids": [
      "dep_anthropic_claude_haiku_4_5_messages_global",
      "dep_aws_bedrock_claude_haiku_4_5_converse_eu"
    ],
    "usage": { "input_tokens": 1000000, "output_tokens": 100000 },
    "requires": { "tool_calling": "supported", "structured_output": "conditional" }
  }'
TypeScript
const comparison = await allm.deployments.compare({
  deploymentIds: [
    "dep_anthropic_claude_haiku_4_5_messages_global",
    "dep_aws_bedrock_claude_haiku_4_5_converse_eu",
  ],
  inputTokens: 1_000_000,
  outputTokens: 100_000,
  requires: {
    tool_calling: "supported",
    structured_output: "conditional",
  },
});

console.log(comparison.data[0].deployment.id);

Request body

deployment_ids
string[]required
Between 1 and 100 candidate deployment IDs.
usage
objectrequired
The same pricing usage shape accepted by the calculate endpoint.
requires
record
capability → supported | conditional. Requiring conditional also accepts supported.

Ranked response

JSON · 200
{
  "data": [
    {
      "deployment": {
        "id": "dep_anthropic_claude_haiku_4_5_messages_global",
        "provider_id": "anthropic",
        "region": "global",
        "capabilities": { "tool_calling": { "status": "supported" } }
      },
      "pricing": { "currency": "USD", "total_usd": "1.500000" }
    },
    {
      "deployment": {
        "id": "dep_aws_bedrock_claude_haiku_4_5_converse_eu",
        "provider_id": "aws-bedrock",
        "region": "eu"
      },
      "pricing": { "currency": "USD", "total_usd": "1.650000" }
    }
  ]
}

Filtering behavior

Unknown deployment IDs, deployments without a token rate card, and candidates that fail requirements are omitted. An empty data array is a valid response meaning that no candidate qualified; it is not a server error.

Recommended workflow

  1. Use List deployments to build the candidate set.
  2. Apply hard requirements in requires.
  3. Compare with a representative usage profile.
  4. Apply non-price preferences such as provider diversity or region.
  5. Persist the selection with the catalog release header.

Response metadata

Every successful response includes x-allm-catalog-release, x-request-id, and an ETag. Store the request ID in logs and the catalog release beside any persisted decision.