Skip to Content

Get model status

GEThttps://api.respan.ai/api/models/{model_name}/status/

Get public uptime and normalized performance metrics for an exact logged model string. Authentication is optional. Public callers receive redacted volume fields.

Servers

https://api.respan.ai: Respan API Server

Authentication

Authentication is optional.

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Or:

DashboardJwt

Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.

HTTP scheme: bearer; format: Dashboard JWT.

HTTP
Authorization: Bearer $RESPAN_DASHBOARD_JWT

Path parameters

Parameter Type Required Description and constraints
model_name string Required
Exact logged model string; provider-prefixed values may contain a slash.

Query parameters

Parameter Type Required Description and constraints
provider_id string or null Optional
Minimum length: 1
start_time string Required
-
end_time string Required
-
time_tick string Optional
Allowed: "minute", "hour", "day"
Default: day

Responses

200

Model status series. Unknown model names return empty series rather than 404.

application/json

Field Type Requirement Description and constraints
$ object Body
Reference: #/components/schemas/ModelStatusResponse
model string Required in parent
-
provider_id string or null Required in parent
-
time_tick string Required in parent
Allowed: "minute", "hour", "day"
start_time string Required in parent
Format: date-time
end_time string Required in parent
Format: date-time
data array<object> Required in parent
-
data[] object Array item
Reference: #/components/schemas/ModelStatusUptimeBucket
data[].date_group string Required in parent
Format: date-time
data[].uptime number or null Required in parent
-
data[].total_count integer Optional
Staff-only.
data[].down_count integer Optional
Staff-only.
respan_uptime array<object> Optional
Omitted when provider_id is supplied.
respan_uptime[] object Array item
Reference: #/components/schemas/ModelStatusUptimeBucket
respan_uptime[].date_group string Required in parent
Format: date-time
respan_uptime[].uptime number or null Required in parent
-
respan_uptime[].total_count integer Optional
Staff-only.
respan_uptime[].down_count integer Optional
Staff-only.
metrics_series array<object> Required in parent
-
metrics_series[] object Array item
Reference: #/components/schemas/ModelStatusMetricBucket
metrics_series[].date_group string Required in parent
Format: date-time
metrics_series[].average_tps number or null Optional
-
metrics_series[].average_ttft number or null Optional
-
metrics_series[].average_latency number or null Optional
-
metrics_series[].cache_hit_percentage number or null Optional
-
metrics_series[].number_of_requests integer Optional
Staff-only.
metrics_series[].cost number or null Optional
Staff-only.
status object Optional
Omitted when provider_id is supplied. Volume fields are staff-only.
status.uptime_percent number or null Optional
-
status.average_tps number or null Optional
-
status.average_ttft number or null Optional
-
status.average_latency number or null Optional
-
status.cache_hit_percentage number or null Optional
-
status.input_cost number or null Optional
-
status.number_of_requests integer Optional
-
status.cost number or null Optional
-
status.prompt_tokens integer Optional
-
status.completion_tokens integer Optional
-
status.prompt_cache_hit_tokens integer Optional
-
status.prompt_cache_creation_tokens integer Optional
-

OpenAPI response schema

{
  "$ref": "#/components/schemas/ModelStatusResponse"
}

400

Invalid timestamps, range, provider, or time tick.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

429

Anonymous callers are limited to 30 requests per minute per IP.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Get model status",
  "operationId": "api_models_status_retrieve",
  "tags": [
    "Models"
  ],
  "description": "Get public uptime and normalized performance metrics for an exact logged model string. Authentication is optional. Public callers receive redacted volume fields.",
  "parameters": [
    {
      "name": "model_name",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string"
      },
      "description": "Exact logged model string; provider-prefixed values may contain a slash."
    },
    {
      "name": "provider_id",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "nullable": true,
        "minLength": 1
      }
    },
    {
      "name": "start_time",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "description": "ISO-8601 or epoch timestamp. Raw window max 90 days."
      }
    },
    {
      "name": "end_time",
      "in": "query",
      "required": true,
      "schema": {
        "type": "string",
        "description": "Timestamp after start_time."
      }
    },
    {
      "name": "time_tick",
      "in": "query",
      "required": false,
      "schema": {
        "type": "string",
        "enum": [
          "minute",
          "hour",
          "day"
        ],
        "default": "day"
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Model status series. Unknown model names return empty series rather than 404.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ModelStatusResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid timestamps, range, provider, or time tick.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "429": {
      "description": "Anonymous callers are limited to 30 requests per minute per IP.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "security": [
    {},
    {
      "RespanApiKey": []
    },
    {
      "DashboardJwt": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "schemas": {
    "ModelStatusMetricBucket": {
      "type": "object",
      "required": [
        "date_group"
      ],
      "properties": {
        "date_group": {
          "type": "string",
          "format": "date-time"
        },
        "average_tps": {
          "type": "number",
          "nullable": true
        },
        "average_ttft": {
          "type": "number",
          "nullable": true
        },
        "average_latency": {
          "type": "number",
          "nullable": true
        },
        "cache_hit_percentage": {
          "type": "number",
          "nullable": true
        },
        "number_of_requests": {
          "type": "integer",
          "description": "Staff-only."
        },
        "cost": {
          "type": "number",
          "nullable": true,
          "description": "Staff-only."
        }
      }
    },
    "ModelStatusResponse": {
      "type": "object",
      "required": [
        "model",
        "provider_id",
        "time_tick",
        "start_time",
        "end_time",
        "data",
        "metrics_series"
      ],
      "properties": {
        "model": {
          "type": "string"
        },
        "provider_id": {
          "type": "string",
          "nullable": true
        },
        "time_tick": {
          "type": "string",
          "enum": [
            "minute",
            "hour",
            "day"
          ]
        },
        "start_time": {
          "type": "string",
          "format": "date-time"
        },
        "end_time": {
          "type": "string",
          "format": "date-time"
        },
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ModelStatusUptimeBucket"
          }
        },
        "respan_uptime": {
          "type": "array",
          "description": "Omitted when provider_id is supplied.",
          "items": {
            "$ref": "#/components/schemas/ModelStatusUptimeBucket"
          }
        },
        "metrics_series": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/ModelStatusMetricBucket"
          }
        },
        "status": {
          "type": "object",
          "description": "Omitted when provider_id is supplied. Volume fields are staff-only.",
          "properties": {
            "uptime_percent": {
              "type": "number",
              "nullable": true
            },
            "average_tps": {
              "type": "number",
              "nullable": true
            },
            "average_ttft": {
              "type": "number",
              "nullable": true
            },
            "average_latency": {
              "type": "number",
              "nullable": true
            },
            "cache_hit_percentage": {
              "type": "number",
              "nullable": true
            },
            "input_cost": {
              "type": "number",
              "nullable": true
            },
            "number_of_requests": {
              "type": "integer"
            },
            "cost": {
              "type": "number",
              "nullable": true
            },
            "prompt_tokens": {
              "type": "integer"
            },
            "completion_tokens": {
              "type": "integer"
            },
            "prompt_cache_hit_tokens": {
              "type": "integer"
            },
            "prompt_cache_creation_tokens": {
              "type": "integer"
            }
          }
        }
      }
    },
    "ModelStatusUptimeBucket": {
      "type": "object",
      "required": [
        "date_group",
        "uptime"
      ],
      "properties": {
        "date_group": {
          "type": "string",
          "format": "date-time"
        },
        "uptime": {
          "type": "number",
          "nullable": true
        },
        "total_count": {
          "type": "integer",
          "description": "Staff-only."
        },
        "down_count": {
          "type": "integer",
          "description": "Staff-only."
        }
      }
    }
  },
  "securitySchemes": {
    "DashboardJwt": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Dashboard JWT",
      "description": "Use a dashboard JWT only for dashboard-authenticated endpoints. Respan API-key endpoints use the respanApiKey auth field instead.",
      "x-fern-bearer": {
        "name": "dashboardJwt",
        "env": "RESPAN_DASHBOARD_JWT"
      }
    },
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}