Axiom

Axiom is a cloud-native observability platform for storing, querying, and analyzing log and event data at scale. Use the REST API to ingest data, run queries using APL (Axiom Processing Language), and manage datasets programmatically.

Official docs: https://axiom.co/docs/restapi/introduction

When to Use

Use this skill when you need to:

• Send logs, metrics, or event data to Axiom
• Query and analyze data using APL (Axiom Processing Language)
• Manage datasets, monitors, and annotations
• Build observability pipelines and dashboards

Prerequisites

1. Create an Axiom account at https://app.axiom.co/register
2. Create an API token with appropriate permissions (Settings > API Tokens)
3. Create a dataset to store your data

Token Types

Axiom supports two token types:

Set environment variables:

# Required: API Token for most operations
export AXIOM_API_TOKEN="xaat-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Optional: For endpoints that require PAT (e.g., Get Current User)
export AXIOM_PERSONAL_ACCESS_TOKEN="xapt-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
export AXIOM_ORG_ID="your-org-id"

Important: When using $VAR in a command that pipes to another command, wrap the command containing $VAR in bash -c '...'. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.

bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"' | jq .

How to Use

Base URLs

• Ingest (US East): https://us-east-1.aws.edge.axiom.co
• Ingest (EU Central): https://eu-central-1.aws.edge.axiom.co
• API: https://api.axiom.co

1. List Datasets

bash -c 'curl -s "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_API_TOKEN}"' | jq .

2. Get Dataset Info

bash -c 'curl -s "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_API_TOKEN}"' | jq .

3. Create Dataset

Write to /tmp/axiom_request.json:

{
  "name": "my-logs",
  "description": "Application logs"
}

Then run:

bash -c 'curl -s -X POST "https://api.axiom.co/v2/datasets" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json' | jq .

4. Ingest Data (JSON)

Write to /tmp/axiom_request.json:

[
  {"message": "User logged in", "user_id": "123", "level": "info"}
]

Then run:

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json' | jq .

5. Ingest Data (NDJSON)

bash -c 'curl -s -X POST "https://us-east-1.aws.edge.axiom.co/v1/ingest/my-logs" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/x-ndjson" -d $'"'"'{"message": "Event 1", "level": "info"}\n{"message": "Event 2", "level": "warn"}'"'"'' | jq .

6. Query Data with APL

Write to /tmp/axiom_request.json:

{
  "apl": "[\"my-logs\"] | where level == \"error\" | limit 10",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

Then run:

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json' | jq .

7. Query with Aggregation

Write to /tmp/axiom_request.json:

{
  "apl": "[\"my-logs\"] | summarize count() by level",
  "startTime": "2024-01-01T00:00:00Z",
  "endTime": "2025-12-31T23:59:59Z"
}

Then run:

bash -c 'curl -s -X POST "https://api.axiom.co/v1/datasets/_apl?format=tabular" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json' | jq .

8. Create Annotation

Write to /tmp/axiom_request.json:

{
  "datasets": ["my-logs"],
  "type": "deployment",
  "title": "v1.2.0 deployed",
  "time": "2024-12-24T10:00:00Z"
}

Then run:

bash -c 'curl -s -X POST "https://api.axiom.co/v2/annotations" -H "Authorization: Bearer ${AXIOM_API_TOKEN}" -H "Content-Type: application/json" -d @/tmp/axiom_request.json' | jq .

9. List Monitors

bash -c 'curl -s "https://api.axiom.co/v2/monitors" -H "Authorization: Bearer ${AXIOM_API_TOKEN}"' | jq .

10. Get Current User (Requires PAT)

Note: This endpoint requires a Personal Access Token (PAT), not an API Token.

bash -c 'curl -s "https://api.axiom.co/v2/user" -H "Authorization: Bearer ${AXIOM_PERSONAL_ACCESS_TOKEN}" -H "x-axiom-org-id: ${AXIOM_ORG_ID}"' | jq .

11. Delete Dataset

bash -c 'curl -s -X DELETE "https://api.axiom.co/v2/datasets/my-logs" -H "Authorization: Bearer ${AXIOM_API_TOKEN}"' | jq .

APL Query Examples

APL (Axiom Processing Language) is similar to Kusto Query Language (KQL). Use ["dataset-name"] syntax for dataset names with special characters.

Guidelines

1. Use Edge URLs for Ingest: Always use the edge endpoint (us-east-1.aws.edge.axiom.co or eu-central-1.aws.edge.axiom.co) for data ingestion, not api.axiom.co
2. Batch Events: Send multiple events in a single request for better performance
3. Include Timestamps: Events without timestamps will use server receive time
4. Rate Limits: Check X-RateLimit-Remaining header to avoid hitting limits
5. APL Time Range: Always specify startTime and endTime for queries to improve performance
6. Data Formats: JSON array is recommended; NDJSON and CSV are also supported