Stored Completions

The Stored Completions API lets you:

List: browse stored completions with filtering by model, metadata, and pagination.
Retrieve: get the full details of a specific completion including usage and parameters.
Update: attach or modify metadata on stored completions for tagging and organization.
Delete: remove stored completions you no longer need.
Messages: retrieve the full message history (input and output) for a completion.

All endpoints require API key authentication and are scoped to the authenticated project. Completions are stored using the platform's standard two-tier storage architecture. For details on storage tiers, encryption, retention, and billing, see Storage.

List Completions

GET /{project_id}/{endpoint_slug}/v1/chat/completions

Returns a paginated list of stored completions for the project.

// queryQuery parameters

Parameter	Type	Description
afteroptional	string	Cursor for pagination. Pass the `id` of the last item from the previous page.
limitoptional	integer	Maximum number of completions to return (1-100, default 20).
orderoptional	string	Sort order: `"asc"` or `"desc"` (default `"desc"`).
modeloptional	string	Filter by model name.
metadata[key]optional	string	Filter by metadata key-value pair. Example: `metadata[env]=production`.

curl

                    curl "https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions?limit=5&order=desc&model=llama3-8b" \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Response

                        {
  "object": "list",
  "data": [
    {
      "id": "chatcmpl-abc123",
      "object": "chat.completion",
      "created": 1700000000,
      "model": "llama3-8b",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! How can I help you today?"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 12,
        "completion_tokens": 9,
        "total_tokens": 21
      },
      "metadata": {"env": "production"},
      "service_tier": "default",
      "system_fingerprint": "fp_abc123"
    }
  ],
  "first_id": "chatcmpl-abc123",
  "last_id": "chatcmpl-abc123",
  "has_more": true
}
                    

Get Completion

GET /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Retrieves a single stored completion by its ID, including full usage details and request parameters.

curl

                    curl https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Response

                        {
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "llama3-8b",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 9,
    "total_tokens": 21,
    "prompt_tokens_details": null,
    "completion_tokens_details": null
  },
  "metadata": {},
  "service_tier": "default",
  "system_fingerprint": "fp_abc123",
  "request_id": "req_xyz789",
  "temperature": 0.7,
  "top_p": 1.0,
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0
}
                    

Update Completion

POST /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Updates the metadata on a stored completion. Use this to tag or annotate completions for later filtering.

// bodyRequest body

Parameter	Type	Description
metadatarequired	object	Key-value pairs to set on the completion. Replaces existing metadata.

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "env": "production",
      "team": "nlp",
      "reviewed": "true"
    }
  }'
                

Response

Returns the updated completion object (same format as Get Completion).

Delete Completion

DELETE /{project_id}/{endpoint_slug}/v1/chat/completions/{id}

Permanently deletes a stored completion and its associated messages.

curl

                    curl -X DELETE https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Response

                        {
  "id": "chatcmpl-abc123",
  "object": "chat.completion.deleted",
  "deleted": true
}
                    

Get Messages

GET /{project_id}/{endpoint_slug}/v1/chat/completions/{id}/messages

Retrieves the full message history for a stored completion, including both the input messages (system, user, tool) and the assistant response.

Each message item carries an object field set to "chat.completion.message", plus the required id, role, and content fields. Optional fields name, tool_calls, and tool_call_id are included when present (tool messages always carry tool_call_id; assistant messages that invoked tools carry tool_calls).

// queryQuery parameters

Parameter	Type	Description
afteroptional	string	Cursor for pagination.
limitoptional	integer	Maximum messages to return (default 20).
orderoptional	string	Sort order: `"asc"` (default) or `"desc"`.

curl

                    curl "https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/chat/completions/chatcmpl-abc123/messages?order=asc" \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Response

                        {
  "object": "list",
  "data": [
    {
      "id": "msg_001",
      "object": "chat.completion.message",
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "id": "msg_002",
      "object": "chat.completion.message",
      "role": "user",
      "content": "Hello!"
    },
    {
      "id": "msg_003",
      "object": "chat.completion.message",
      "role": "assistant",
      "content": "Hello! How can I help you today?"
    }
  ],
  "first_id": "msg_001",
  "last_id": "msg_003",
  "has_more": false
}
                    

Client Examples

// pythonPython (requests)

Python

                    import requests

headers = {
    "Authorization": "Bearer xero_myproject_your_api_key",
    "Content-Type": "application/json"
}
base = "https://api.xerotier.ai/proj_ABC123/my-endpoint/v1"

# List stored completions
completions = requests.get(
    f"{base}/chat/completions?limit=5&order=desc",
    headers=headers
).json()
for c in completions["data"]:
    print(f"{c['id']} - {c['model']} ({c['usage']['total_tokens']} tokens)")

# Get a specific completion
comp = requests.get(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers
).json()
print(f"Model: {comp['model']}, Finish: {comp['choices'][0]['finish_reason']}")

# Update completion metadata
requests.post(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers,
    json={
        "metadata": {
            "env": "production",
            "reviewed": "true"
        }
    }
)

# Get completion messages
messages = requests.get(
    f"{base}/chat/completions/chatcmpl-abc123/messages?order=asc",
    headers=headers
).json()
for msg in messages["data"]:
    print(f"[{msg['role']}] {msg['content']}")

# Delete a completion
requests.delete(
    f"{base}/chat/completions/chatcmpl-abc123",
    headers=headers
)
                

// nodeNode.js (fetch)

JavaScript

                    const base = "https://api.xerotier.ai/proj_ABC123/my-endpoint/v1";
const headers = {
    "Authorization": "Bearer xero_myproject_your_api_key",
    "Content-Type": "application/json"
};

// List stored completions
const listRes = await fetch(
    `${base}/chat/completions?limit=5&order=desc`,
    { headers }
);
const completions = await listRes.json();
completions.data.forEach(c =>
    console.log(`${c.id} - ${c.model} (${c.usage.total_tokens} tokens)`)
);

// Get a specific completion
const compRes = await fetch(
    `${base}/chat/completions/chatcmpl-abc123`,
    { headers }
);
const comp = await compRes.json();
console.log(`Model: ${comp.model}`);

// Update completion metadata
await fetch(`${base}/chat/completions/chatcmpl-abc123`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        metadata: { env: "production", reviewed: "true" }
    })
});

// Get completion messages
const msgsRes = await fetch(
    `${base}/chat/completions/chatcmpl-abc123/messages?order=asc`,
    { headers }
);
const messages = await msgsRes.json();
messages.data.forEach(msg =>
    console.log(`[${msg.role}] ${msg.content}`)
);

// Delete a completion
await fetch(`${base}/chat/completions/chatcmpl-abc123`, {
    method: "DELETE",
    headers
});
                

Error Handling

Error responses currently use the envelope type values invalid_request_error for 4xx (including 404 resource lookups) and internal_error for 5xx. These envelope type strings are tracked for alignment with the OpenAI spec (not_found_error, server_error) in a future release.

json

                    {
  "error": {
    "type": "invalid_request_error",
    "code": "completion_not_found",
    "message": "Completion 'chatcmpl-abc123' does not exist or does not belong to this project.",
    "param": null
  }
}
                

// codesStatus codes

HTTP Status	Error Code	Description
400	`invalid_request`	Missing or invalid parameters.
401	`authentication_error`	Invalid or missing API key.
404	`completion_not_found`	The specified completion ID does not exist or does not belong to your project.
429	`rate_limit_exceeded`	Too many requests. Check the `Retry-After` header.
500	`internal_error`	Server-side failure. Retry the request.