Menu

Nutzungsstatistiken

Endpoint: Nutzungsstatistiken

Die Usage-Endpoints liefern Statistiken über deine API-Nutzung und den aktuellen Kontingent-Status.

GET /api/v1/usage/stats

Liefert aggregierte Nutzungsstatistiken.

Scope erforderlich: usage:read

Query-Parameter

Parameter Typ Standard Beschreibung
period String quarter Zeitraum: day, week, month, quarter, year

Beispiel-Request

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/usage/stats?period=month" \
  -H "Authorization: Bearer rfk_dein_token"

Beispiel-Response

{
  "stats": {
    "total_requests": 15234,
    "successful_requests": 15012,
    "failed_requests": 222,
    "matching_requests": 4521,
    "grants_requests": 10713,
    "active_organizations": 89,
    "average_response_time_ms": 145,
    "by_endpoint": {
      "grants.index": 8432,
      "grants.show": 2281,
      "matching.create": 4521
    },
    "by_day": [
      {
        "date": "2026-01-29",
        "requests": 523,
        "matching_requests": 156
      },
      {
        "date": "2026-01-28",
        "requests": 612,
        "matching_requests": 189
      }
    ]
  },
  "period": "month",
  "partner": {
    "name": "Partner GmbH",
    "tier": "standard"
  }
}

Stats-Felder

Feld Typ Beschreibung
total_requests Integer Gesamtanzahl Anfragen
successful_requests Integer Erfolgreiche Anfragen (2xx)
failed_requests Integer Fehlgeschlagene Anfragen (4xx, 5xx)
matching_requests Integer Anzahl Matching-Anfragen
grants_requests Integer Anzahl Grant-Anfragen
active_organizations Integer Eindeutige Organisationen mit Matching
average_response_time_ms Integer Durchschnittliche Antwortzeit
by_endpoint Object Aufschlüsselung nach Endpoint
by_day Array Tägliche Aufschlüsselung

GET /api/v1/usage/quota

Liefert den aktuellen Kontingent-Status.

Scope erforderlich: usage:read

Beispiel-Request

curl -X GET "https://foerdermittelkompass.reflecta.org/api/v1/usage/quota" \
  -H "Authorization: Bearer rfk_dein_token"

Beispiel-Response

{
  "quota": {
    "quarter": "2026-Q1",
    "tier": "standard",
    "active_organizations": {
      "current": 89,
      "limit": 500,
      "percentage": 17.8
    },
    "matching_requests": {
      "current": 4521,
      "limit": 50000,
      "percentage": 9.04
    },
    "status": "ok",
    "warning": false,
    "exceeded": false
  }
}

Quota-Felder

Feld Typ Beschreibung
quarter String Aktuelles Quartal (z.B. "2026-Q1")
tier String Dein Tier: starter, standard, enterprise
active_organizations.current Integer Aktive Organisationen dieses Quartal
active_organizations.limit Integer Limit für aktive Organisationen
active_organizations.percentage Float Auslastung in %
matching_requests.current Integer Matching-Anfragen dieses Quartal
matching_requests.limit Integer Fair-Use-Kontingent
matching_requests.percentage Float Auslastung in %
status String Status: ok, warning, exceeded
warning Boolean True wenn >= 90% Auslastung
exceeded Boolean True wenn Limit überschritten

Status-Werte

Status Bedeutung Aktion
ok Unter 90% Auslastung Keine Aktion nötig
warning 90-100% Auslastung Kontaktiere uns für Upgrade
exceeded Über 100% Anfragen werden weiter akzeptiert, aber Abrechnung erfolgt

Tier-Limits

Tier Aktive Orgs Matching-Anfragen/Jahr
Starter 100 10.000
Standard 500 50.000
Enterprise 1.000 100.000

Fehler

Status Code Beschreibung
401 unauthorized Authentifizierung fehlgeschlagen
403 insufficient_scope Token hat nicht usage:read Scope

War diese Seite hilfreich?