Account & usage

Four read-only endpoints expose everything you need to drive an in-app status page or a usage report:

Endpoint	What it returns
GET /api/v1/me	Balance, pricing tier, signup trial, active credit grants.
GET /api/v1/tiers	Tier ladder, your current tier, progress to the next.
GET /api/v1/usage	Paginated charge history (one row per billed event).
GET /api/v1/jobs	Paginated async job list (forecasts today).

All monetary fields are integer EUR cents (100 = €1.00). Top-ups, payment methods, and auto top-up settings are managed in the Developers Portal — not via this API.

Read your balance and tier

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/me \
  | jq '{tier: .api_usage_tier, balance: .available_eur_cents, trial: .signup_trial.remaining_eur_cents}'

Python

import os

from sybilion import Client

client = Client(token=os.environ["SYBILION_API_TOKEN"])

me = client.raw.api_v1_me_get()
trial_left = me.signup_trial.remaining_eur_cents if me.signup_trial else 0
print(
    "tier:", me.api_usage_tier,
    "balance:", me.available_eur_cents,
    "trial_left:", trial_left,
)

Go

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"go.sybilion.dev/sybilion"
)

func main() {
	c := sybilion.New(sybilion.Options{
		Token: os.Getenv("SYBILION_API_TOKEN"),
	})

	me, _, err := c.DefaultAPI().ApiV1MeGet(context.Background()).Execute()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("tier=%d balance=%d\n",
		me.GetApiUsageTier(), me.GetAvailableEurCents())
}

Balance vs available

balance_eur_cents is your ledger total. available_eur_cents subtracts active holds for in-flight async forecast jobs. When a job settles or fails, its hold is released and available_eur_cents moves back toward balance_eur_cents. Spend decisions (will this call go through?) should always read available_eur_cents.

Active credit grants

Each grant — signup trial, top-up, partner credit — appears as a row in euro_tranches[] with remaining_eur_cents, expires_at, and source. Tranches are spent in expires_at ascending order, so soon-to-expire credit is used first.

Tier and progress

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  https://api.sybilion.dev/api/v1/tiers \
  | jq '{current: .current_tier, next: .next_tier, progress: .progress}'

Python

tiers = client.raw.api_v1_tiers_get()
print("current:", tiers.current_tier, "next:", tiers.next_tier)
print("progress:", tiers.progress)

Go

tiers, _, err := c.DefaultAPI().ApiV1TiersGet(context.Background()).Execute()
if err != nil {
	log.Fatal(err)
}
fmt.Println("current:", tiers.GetCurrentTier(), "next:", tiers.GetNextTier())

progress carries the live values that move you to the next tier (lifetime paid, payment count, max single payment). Concept and tier names: Tiers & signup trial.

Paginated usage history

One row per billed event (async settlement or synchronous billed call). Use page / limit (max 200 per page) and sort / order to walk the list.

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  "https://api.sybilion.dev/api/v1/usage?page=1&limit=20&sort=created_at&order=desc" \
  | jq '{total: .pagination.total, first: .usage_events[0]}'

Python

total = 0
for page in client.iter_usage_pages(limit=50):
    total += len(page.usage_events)
print("usage events:", total)

Go

resp, _, err := c.DefaultAPI().ApiV1UsageGet(context.Background()).
	Page(1).Limit(50).Sort("created_at").Order("desc").Execute()
if err != nil {
	log.Fatal(err)
}
fmt.Println("page total:", resp.Pagination.GetTotal())

Paginated job list

Lightweight summaries of your async jobs. For a single job's full state and artifacts use GET /api/v1/forecasts/:id.

curl

curl -sS -H "Authorization: Bearer $SYBILION_API_TOKEN" \
  "https://api.sybilion.dev/api/v1/jobs?page=1&limit=20&status=completed" \
  | jq '.jobs[0]'

Python

for page in client.iter_jobs_pages(limit=50, status="completed"):
    for job in page.jobs:
        print(job.job_id, job.status, job.eur_cents_final)

Go

resp, _, err := c.DefaultAPI().ApiV1JobsGet(context.Background()).
	Page(1).Limit(50).Status("completed").Execute()
if err != nil {
	log.Fatal(err)
}
for _, j := range resp.Jobs {
	fmt.Println(j.GetJobId(), j.GetStatus(), j.GetEurCentsFinal())
}

Visibility window

Some older completed jobs may be filtered out of /jobs when a post-settlement visibility window is in effect — the same rule applies on the per-job endpoint. You won't see a row in the list whose detail page would respond 404.

See also

• API reference: GET /api/v1/me · GET /api/v1/tiers · GET /api/v1/usage · GET /api/v1/jobs
• Tiers & signup trial — what each tier unlocks.
• Clients: Using curl · Python SDK · Go SDK.