Skip to main content
This guide routes one request through the hosted Astrolabe Cloud gateway.

​
Before you start

You need:
  • An Astrolabe Cloud account at https://app.astrolabe.run
  • A funded workspace balance
  • A workspace API key

​
1. Open the Cloud app

Sign in at https://app.astrolabe.run. Astrolabe creates or loads your workspace after sign-in. If your workspace is pending access review, complete the access request first.

​
2. Add prepaid credits

Go to Billing and buy a prepaid credit pack. Astrolabe reserves balance before each gateway request and finalizes the exact debit after provider usage is known. Requests are rejected before provider work starts when the available balance is too low.

​
3. Create an API key

Go to API keys, create a key, and copy the secret once. Use it as a bearer token: 
Authorization: Bearer astrolabe_live_...
You can also send the same value as: 
x-api-key: astrolabe_live_...

​
4. Send a Responses request

curl https://api.astrolabe.run/v1/responses \
  -H "Authorization: Bearer $ASTROLABE_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "astrolabe/auto",
    "input": "Write one sentence explaining routing stacks."
  }'
Python with the OpenAI client: 
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_ASTROLABE_CLOUD_KEY",
    base_url="https://api.astrolabe.run/v1",
)

response = client.responses.create(
    model="astrolabe/auto",
    input="Route this through my default Astrolabe stack.",
)

​
5. Inspect response headers

Every routed response includes headers you can log for support and analysis:
  • x-astrolabe-cloud-request-id
  • x-astrolabe-cloud-workspace
  • x-astrolabe-cloud-key
  • x-ratelimit-limit
  • x-ratelimit-remaining
  • x-ratelimit-reset
  • x-astrolabe-model
  • x-astrolabe-stack-name
  • x-astrolabe-stack-version
  • x-astrolabe-policy-status
Additional headers may include category, complexity, lane, selected provider, selected model, confidence, estimated baseline cost, and estimated savings.

​
6. Select a specific stack

Add metadata.astrolabe.stack when you want one request to use a specific stack slug: 
curl https://api.astrolabe.run/v1/responses \
  -H "Authorization: Bearer $ASTROLABE_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "astrolabe/auto",
    "input": "Summarize this customer escalation.",
    "metadata": {
      "astrolabe": {
        "stack": "customer-data",
        "quality": "high",
        "verification": "strong"
      }
    }
  }'
See Request Stack Selection for the full override contract.