Developer Hub

Welcome to the ModelVantage Developer Hub. Our platform actively pings the world's leading Large Language Model (LLM) endpoints from multiple AWS regions every single minute. Rather than relying on vendor status pages—which are often self-reported and lag real incidents by 30 to 60 minutes—ModelVantage acts as an independent, neutral third-party monitor, ensuring you know about outages and regional latency spikes before your users do.

API Capabilities

ModelVantage exposes robust programmatic access to both current and historical performance data:

• Real-Time Snapshots: Access end-to-end latency and HTTP status codes for every active model/region combination within seconds.
• Historical Archive: Retrieve granular historical poll records with up to a 90-day lookback window for in-depth regional analysis.
• Webhook Push Alerts: Dispatch real-time notifications to your servers or Slack channels the instant a model degrades or recovers.
• SLA Certifications: Systematically download timestamped compliance PDF reports to substantiate vendor credit claims. Paid plans include a 5 monthly download quota.

Subscriber Onboarding

Getting integrated with the ModelVantage API takes less than five minutes. Follow these simple steps to register, generate secure credentials, and issue your first authorized API call:

1. Purchase a Subscription: Sign up for a subscription plan via our landing page. Billing and access are secured and managed seamlessly through Stripe.
2. Authenticate on the Developer Portal: Navigate to the ModelVantage Developer Portal. Enter the email address associated to your subscription. A 6-digit One-Time Password (OTP) will be sent to your inbox. Enter the code to log-in to the portal.
3. Generate Your API Key: In the portal dashboard, locate the "API Keys" widget and click "Create New Key". Provide a descriptive label (e.g., Production Gateway).

   Security Boundary: Your newly generated API key (prefixed with mv_live_) is displayed **exactly once**. If you lose this key, you must generate a new one.

4. Pass the Key in Request Headers: All REST API calls require your API key to be passed in the X-API-Key request header. See the example below:

   GET /v1/snapshot HTTP/1.1
   Host: api.modelvantage.com
   X-API-Key: mv_live_your_actual_key_token_here
   Accept: application/json

REST API Guide

All request endpoints are served over HTTPS relative to our global API gateway:
https://api.modelvantage.com/v1

Rate Limits

To maintain high availability and prevent resource exhaustion, the ModelVantage REST API implements sliding-window rate limiting:

• Rate Limit: 60 requests per minute (evaluated using a sliding window per API key).

Usage Response Headers

Every API response includes real-time telemetry headers detailing your current consumption status:

Sentinel Values

Endpoint Reference

GET /snapshot

Retrieves the latest probe telemetry records for every monitored model and AWS region combination. This endpoint acts as a live, real-time pulse of the AI ecosystem.

Caching Policy: Responses are cached globally for 30 seconds. Consecutive queries within the 30-second window will return identical payload data and timestamp fields, but will still consume rate limits.

Response Schema

Returns a JSON object containing the generation timestamp and a list of active model configurations:

• snapshot_at (string, ISO-8601): The generation timestamp (UTC) of this snapshot data.
• models (array): List of active model status entries.
  • provider (string): The AI provider name (e.g., openai, anthropic, google).
  • model_id (string): The model ID (e.g., gpt-5.4, claude-sonnet-4-6, gemini-2.5-flash).
  • region (string): The AWS region from which the minute check was initiated (e.g., us-east-1, us-west-2, eu-west-1, ap-southeast-1, us-east-2).
  • http_status (integer): The raw HTTP response status code. Returns -1 on timeouts/failures.
  • latency_ms (integer): The raw end-to-end execution latency in milliseconds. Returns -1 on timeouts/failures.
  • polled_at (string, ISO-8601): The exact UTC timestamp when this model probe was completed.

Example JSON Response

{
  "snapshot_at": "2026-06-21T22:00:00Z",
  "models": [
    {
      "provider": "openai",
      "model_id": "gpt-5.4",
      "region": "us-east-1",
      "http_status": 200,
      "latency_ms": 342,
      "polled_at": "2026-06-21T21:59:47Z"
    },
    {
      "provider": "anthropic",
      "model_id": "claude-sonnet-4-6",
      "region": "eu-west-1",
      "http_status": 200,
      "latency_ms": 512,
      "polled_at": "2026-06-21T21:59:41Z"
    },
    {
      "provider": "google",
      "model_id": "gemini-2.5-flash",
      "region": "us-west-2",
      "http_status": -1,
      "latency_ms": -1,
      "polled_at": "2026-06-21T21:59:39Z"
    }
  ]
}

GET /archive

Queries historically archived poll records from our database. Telemetry records are ordered chronologically by polled_at descending (newest first). This endpoint utilizes cursor-based keyset pagination to handle massive query result sets efficiently.

Keyset Pagination Mechanics

ModelVantage utilizes keyset pagination.

• Extracting Cursor: When executing a query, if additional records exist, the response object returns pagination.has_more = true and exposes a token under pagination.next_cursor.
• Fetching the Next Page: For the subsequent query, supply this cursor token unmodified in your query parameters as ?cursor=.... Cursors are encrypted, tokens—so do not attempt to construct them manually. When no more records are available, has_more will return false and next_cursor will evaluate to null.

Example JSON Response

{
  "data": [
    {
      "id": 4829301,
      "provider": "openai",
      "model_id": "gpt-5.4",
      "region": "us-east-1",
      "polled_at": "2026-06-21T21:59:47Z",
      "latency_ms": 342,
      "http_status": 200
    },
    {
      "id": 4829298,
      "provider": "openai",
      "model_id": "gpt-5.4",
      "region": "us-east-1",
      "polled_at": "2026-06-21T21:54:51Z",
      "latency_ms": 298,
      "http_status": 200
    },
    {
      "id": 4829195,
      "provider": "openai",
      "model_id": "gpt-5.4",
      "region": "us-east-1",
      "polled_at": "2026-06-21T21:49:53Z",
      "latency_ms": -1,
      "http_status": -1
    }
  ],
  "pagination": {
    "limit": 100,
    "has_more": true,
    "next_cursor": "eyJwb2xsZWRfYXQiOiAiMjAyNi0wNi0yMVQyMTo0NDo0OFoiLCAiaWQiOiA0ODI5MTAyfQ==",
    "returned_count": 3
  }
}

Real-Time Alerts

Slack Integration & Webhook Setup

ModelVantage can directly notify your teams directly of outages, performance degradations, and system recoveries, in real time.

Slack Integration

Integrate directly with your engineering or operations channels in seconds:

1. Navigate to your Slack Workspace App configuration page and generate an "Incoming Webhook" URL (e.g., https://hooks.slack.com/services/...).
2. In the ModelVantage Developer Portal, locate the Slack Alerts module. Click "Add Webhook" and paste your Slack webhook URL.
3. Click "Send Test Event" to dispatch a simulated notification message directly into your Slack channel to verify the pipeline. (Each configured alert supports up to 5 mock test events before locking).

Generic Webhook Payload Schemas

For custom backend services or automation pipelines, configure generic webhook endpoints in the portal. ModelVantage fires structured JSON payloads via POST requests with standard content headers.

Event Types

• model.outage: Dispatched immediately when a monitored model stops responding completely (returns non-200 or times out).
• model.degraded: Fired when 1-hour average latency exceeds 1,000 ms or error rate rises above 1%.
• model.recovered: Triggered the moment a degraded or down model resumes normal, stable telemetry values.

Webhook Payload JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "WebhookEventPayload",
  "type": "object",
  "required": ["event", "timestamp", "data"],
  "additionalProperties": false,
  "properties": {
    "event": {
      "type": "string",
      "enum": ["model.outage", "model.degraded", "model.recovered"]
    },
    "timestamp": {
      "type": "integer",
      "description": "Unix epoch timestamp when the webhook event was generated."
    },
    "data": {
      "type": "object",
      "required": ["model", "provider", "status", "message"],
      "additionalProperties": false,
      "properties": {
        "model": {
          "type": "string",
          "description": "The identifier of the affected AI model."
        },
        "provider": {
          "type": "string",
          "enum": ["openai", "anthropic", "google"]
        },
        "status": {
          "type": "string",
          "enum": ["outage", "degraded", "operational"]
        },
        "message": {
          "type": "string",
          "description": "Human-readable summary of the performance event."
        }
      }
    }
  }
}

Example Payload Body

{
  "event": "model.outage",
  "timestamp": 1750550460,
  "data": {
    "model": "gpt-4o",
    "provider": "openai",
    "status": "outage",
    "message": "Model gpt-4o is currently experiencing an outage."
  }
}

Webhook Security & Cryptographic Signatures

ModelVantage signs every webhook payload cryptographically. All webhook POST requests include an X-ModelVantage-Signature header.

Signing Logic

When you register a webhook in our portal, we generate a unique signing secret prefixed with whsec_. Every outgoing webhook POST includes an X-ModelVantage-Signature header containing:

• Timestamp (t): The Unix epoch time (seconds UTC) when the webhook was dispatched.
• HMAC-SHA256 Signature (v1): Computed over the message "t={timestamp}." + payload_bytes using your signing secret as the HMAC key.

The full header format is:
X-ModelVantage-Signature: t=1750550460,v1=9e3a6bc42f8832bd1a886ee90432bc977e2ffbc77daef60667e6ee3bc9192931

To verify, re-compute the HMAC-SHA256 over the timestamp-prefixed payload and compare using a constant-time equality function.

Verification Example (Python)

import hmac
import hashlib
import time

def verify_signature(payload: bytes, secret: str, header: str, tolerance_sec: int = 300) -> bool:
    try:
        parts = dict(item.split("=") for item in header.split(","))
        timestamp = int(parts["t"])
        received_sig = parts["v1"]
    except (KeyError, ValueError):
        return False

    if abs(int(time.time()) - timestamp) > tolerance_sec:
        return False

    message = f"t={timestamp}.".encode() + payload
    expected_sig = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected_sig, received_sig)

Service Level Agreements (SLAs)

Track whether your AI providers are meeting their uptime commitments. ModelVantage independently measures availability across every monitored model and region, giving you objective data to support SLA credit claims.

Custom SLA Thresholds

Every contract has its own uptime guarantees. Set a monthly target that matches your agreements:

• Define your custom monthly uptime threshold — any value between 90.00% and 99.99%.
• Your threshold takes effect immediately and ModelVantage evaluates every monitored model against it in real time.

Monthly Compliance Reports

At the end of each billing cycle, ModelVantage generates a signed, timestamped PDF audit report:

• Uptime Tracking: Reports show actual regional uptime for every monitored endpoint. When availability falls below your threshold, the month is flagged with an "SLA Violation" marker.
• Dispute Evidence: Use these independently verified reports as supporting documentation when filing SLA credit requests with OpenAI, Anthropic, or Google.
• Download Access: Paid plans include a 5 monthly download quota to manage bandwidth usage.

Developer Support

We pride ourselves on providing high-resolution developer-to-developer customer support. All premium subscription tiers feature priority queueing:

• Response Expectation: Guaranteed next-business-day response for all support tickets.
• Direct Email Contact: For any integration hurdles, custom endpoint requests, volume quotes, or billing adjustments, email our core engineering staff directly at support@modelvantage.com.

Error Code Reference

The ModelVantage Customer API returns standard HTTP response codes alongside structural JSON error envelopes.