Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Kulurajat

Oppitunti 7 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Hallitse API-kustannuksiasi
  2. Tarkista nykyiset rajat
  3. Aseta rajat
  4. Tarkista nykyiset veloitukset
  5. Automatisoi kustannusten seuranta
  6. Säädä rajoja dynaamisesti
  7. Keskeiset asiat

Hallitse API-kustannuksiasi

Kulurajat ovat taloudellinen turvaverkkosi. Ne asettavat katon, jonka ylittyessä API-pyynnöt evätään, mikä estää odottamattomat kulut kuukauden lopussa. Management API:n avulla voit tarkastella ja asettaa nämä rajat ohjelmallisesti.

Tarkista nykyiset rajat

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Vastaus näyttää nykyisen jakson katon ja tämänhetkisen kulutuksesi – eli erotuksena jäljellä olevan marginaalisi. Tämä on ainoa luku, joka merkitsee päivittäisessä käytössä: katto ilman kulutustietoja ei kerro, oletko käyttänyt budjetistasi 10 % vai 95 %.

Aseta rajat

curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "monthlyLimit": 500.00
  }'

Toiminta rajan ylittyessä

Tässä on lohduttava osuus, joka kannattaa sanoa ääneen: rajan saavuttaminen ei koskaan johda yoveloitukseen. Pyynnöt evätään, eikä laskutusta synny katon yli. Riski siirtyy taloudellisesta saatavuuteen – ja juuri näin haluatkin, sillä käyttökatkos diagnosoidaan ja korjataan minuuteissa, kun taas odottamaton lasku huomataan liian myöhään.

Kun kulutus saavuttaa asetetun rajan:

  • API-pyynnöt evätään tietyllä virhekoodilla
  • API-avaimet pysyvät aktiivisina, mutta päättelypyynnöt (inference calls) epäonnistuvat
  • Raja nollautuu seuraavan laskutusjakson alussa

Rajastrategia ympäristöittäin

Jos tiimilläsi on useita projekteja, rajan tulisi heijastaa kunkin ympäristön erityisriskejä. Kehitysympäristössä tyypillinen vaara on vahingossa syntynyt pyyntösilmukka – esimerkiksi testiskripti, joka pyörii koko yön – ja matala 50–100 dollarin raja muuttaa tämän virheen 10 dollarin tapaukseksi eikä 1 000 dollarin yllätykseksi. Testiympäristössä (staging) ajetaan kuormitustestejä, jotka kuluttavat perustellusti enemmän: kohtuullinen 200–500 dollarin raja jättää tilaa testikampanjoille pitäen samalla turvavälin. Tuotantoympäristöä ei kuitenkaan saa koskaan kuristaa niin paljon, että asiakaspyynnöt evätään: korkeampi raja (1 000 dollaria ja yli liikenteestä riippuen) vaatii aktiivista seurantaa – hälytys suojaa sinua, kun taas raja on vain viimeisenä keinona toimiva turvaverkko.

Tarkista nykyiset veloitukset

Nähdäksesi tilanteesi nykyisessä jaksossa:

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Tämä päätepiste palauttaa jakson alusta kertyneet veloitukset. Verrattuna kuluneisiin päiviin se antaa enemmän kuin pelkän tilannekuvan: se on ennuste. Budjetin 40 %:n kuluttaminen kuukauden ensimmäisen kolmanneksen aikana on terveellistä; sama 40 % kuukauden kymmenyksen kohdalla ennakoi ylitystä, ja sinulla on vielä 27 päivää aikaa toimia.

Automatisoi kustannusten seuranta

Kynnysarvohälytysskripti

import requests

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
ALERT_THRESHOLD = 0.80  # Hälyytä 80 %:n kohdalla rajasta

# Hae raja
limits_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/spending-limits",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
monthly_limit = limits_resp.json().get("monthlyLimit", 0)

# Hae nykyinen kulutus
preview_resp = requests.get(
    f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/invoice/preview",
    headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
current_spend = preview_resp.json().get("totalAmount", 0)

# Tarkista kynnysarvo
if monthly_limit > 0:
    ratio = current_spend / monthly_limit
    if ratio >= ALERT_THRESHOLD:
        print(f"HÄLYTYS: {ratio*100:.1f}% rajasta saavutettu")
        print(f"  Kulutus: ${current_spend:.2f} / ${monthly_limit:.2f}")
        # Lähetä ilmoitus

Integrointi seurantaan

Yhdistä laskutusesikatselu seurantaratkaisuusi (Grafana, Datadog jne.) luodaksesi reaaliaikaisia kustannusmittaristoja:

# Hae nykyinen summa lähetettäväksi mittarijärjestelmääsi
CURRENT_SPEND=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('totalAmount', 0))")

echo "xai.billing.current_spend:$CURRENT_SPEND|g" | nc -u -w1 localhost 8125

Säädä rajoja dynaamisesti

Raja ei ole kiveen hakattu koko laskutusjaksoksi – ja se on hyvä asia, sillä tuotteen elinkaari ei noudata kirjanpitokalenteria. Ennen odotettua liikennepiikkiä, tuotelanseerausta tai markkinointikampanjaa nosta rajaa väliaikaisesti: mikään ei ole pahempaa kuin maksettu kampanja, joka ohjaa käyttäjiä palveluun, jonka API evää pyynnöt saavutetun katon vuoksi. Päinvastoin, jos kuukauden budjetti on kulunut odotettua nopeammin, rajan alentaminen loppujaksoksi muuttaa driftin hallituksi rajoitteeksi. Kriittisin tapaus on kuitenkin kustannustapaus – silmukka tuotannossa, havaittu väärinkäyttö: rajan välitön alentaminen on hätäpysäytyspainikkeesi, joka pysäyttää vuotoa aiheuttavan toiminnan samalla kun etsit syytä.

# Nosta väliaikaisesti lanseerausta varten
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 2000.00}'

# Palauta normaali raja piikin jälkeen
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"monthlyLimit": 500.00}'

Keskeiset asiat

  • Käytä GET- ja POST-pyyntöjä osoitteeseen /v1/billing/teams/{teamId}/postpaid/spending-limits rajojen tarkasteluun ja asettamiseen
  • Kun raja ylittyy, API-pyynnöt evätään (ei yoveloitusta)
  • Laskutusesikatselu (invoice/preview) mahdollistaa kulutuksen seurannan reaaliajassa
  • Automatisoi kynnysarvohälytykset ennakoimaan ylityksiä
  • Sovata rajat ympäristön mukaan (kehitys, testaus, tuotanto)