Authentication & API Setup

All ZQ Platform APIs share common authentication, rate limiting, and error handling.

Base URL: https://api.zettaquant.ai

---

Authentication

All API requests require an API key passed in the x-api-key header.

curl -H "x-api-key: $ZQ_API_KEY" \
  https://api.zettaquant.ai/v1/models

Getting an API Key

Contact contact@zettaquant.ai to request access.

Keeping Your API Key Safe

warning

Treat your API key like a password.

DO	DON'T
Store in environment variables	Hardcode in source code
Use secrets manager (GCP Secret Manager, AWS Secrets)	Commit to git repositories
Rotate keys periodically	Share keys between environments

Example: Using Environment Variables

# Set in your shell profile (~/.bashrc or ~/.zshrc)
export ZQ_API_KEY="your_api_key_here"
export ZQ_BASE_URL="https://api.zettaquant.ai"

# Use in requests
curl -H "x-api-key: $ZQ_API_KEY" $ZQ_BASE_URL/v1/models

---

Rate Limits

Plan	Monthly Requests	Batch Size
Free	1000	128 texts
Pro	100,000	128 texts
Enterprise	Custom	Custom

• Limits reset at 00:00 UTC daily
• Exceeding limits returns 429 Too Many Requests
• Check your usage: GET /v1/usage/me

Handling Rate Limits

import time
import requests

def request_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        
        if response.status_code == 429:
            wait_time = 2 ** attempt
            print(f"Rate limited. Waiting {wait_time}s...")
            time.sleep(wait_time)
            continue
        
        response.raise_for_status()
        return response.json()
    
    raise Exception("Max retries exceeded")

---

Error Codes

Code	Meaning	Description
400	Bad Request	Invalid request format or parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient tier for requested resource
404	Not Found	Model or dataset not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error (contact support)

Error Response Format:

{
  "detail": "Description of the error"
}

---

Check Your Usage

Monitor your API usage with the usage endpoint.

GET /v1/usage/me

Example:

curl -H "x-api-key: $ZQ_API_KEY" \
  "$ZQ_BASE_URL/v1/usage/me?days=7"

Response:

{
  "email": "user@company.com",
  "tier": "pro",
  "org": "YourOrganization",
  "quota": {
    "monthly_limit": 100000,
    "used": 12500,
    "remaining": 87500,
    "usage_percent": 12.5,
    "resets_at": "2026-04-01T00:00:00Z",
    "period": "2026-03"
  },
  "daily_usage": {
    "2026-03-20": 120,
    "2026-03-19": 95,
    "2026-03-18": 140,
    "2026-03-17": 80,
    "2026-03-16": 200,
    "2026-03-15": 60,
    "2026-03-14": 110
  },
  "period_days": 7,
  "total_requests_period": 805,
  "lifetime": {
    "total_requests": 15420,
    "member_since": "2025-12-10T10:30:00Z"
  }
}

---

Next Steps

• Models Service → - Run inference on financial AI models
• Insights Service → - Access pre-computed metrics