Skip to content
VynCo is in early access — some features may be unavailable.

Sistema di crediti

Comprenda come funzionano i crediti VynCo — costi per operazione, quote per livello, fatturazione del consumo eccessivo e best practice

How It Works

Every API operation that retrieves or generates data costs a fixed number of credits. Credits are deducted from your team's monthly balance when a request succeeds. Management operations (balance, API keys, team info) are always free.

Fixed per-operation cost

Each endpoint has a deterministic credit cost. No surprise charges based on response size.

Debit on success only

Credits are only consumed on HTTP 2xx responses. Failed requests are never charged.

Real-time visibility

Every response includes X-Credits-Used and X-Credits-Remaining headers.

Operation Costs

The table below lists the credit cost for every API operation. Simple lookups cost 1 credit; AI dossiers scale with depth.

OperationEndpointCreditsAvailable on
Company SearchGET /companies1 creditAll
Company Lookup (by UID)GET /companies/{uid}1 creditAll
Company CountGET /companies/count1 creditAll
Company StatisticsGET /companies/statistics1 creditAll
Enriched ProfileGET /companies/{uid} (enriched)5 creditsStarter+
Change Feed QueryGET /changes2 creditsStarter+
Company Change HistoryGET /changes/company/{uid}2 creditsStarter+
Person LookupGET /persons/{uid}3 creditsStarter+
Person SearchPOST /persons/search3 creditsStarter+
Dossier — SummaryPOST /dossiers (level: summary)20 creditsProfessional+
Dossier — StandardPOST /dossiers (level: standard)50 creditsProfessional+
Dossier — ComprehensivePOST /dossiers (level: comprehensive)100 creditsProfessional+
Timeline ExportPOST /timeline/export10 creditsProfessional+
Clustering (K-Means / GMM)POST /analytics/cluster15 creditsProfessional+
Anomaly Detection (Z-score / DBSCAN)POST /analytics/anomalies15 creditsProfessional+
Cohort AnalysisGET /analytics/cohorts20 creditsProfessional+
Company RelationshipsGET /companies/{uid}/relationships10 creditsStarter+
Company Hierarchy TreeGET /companies/{uid}/hierarchy10 creditsStarter+
Company NewsGET /companies/{uid}/news2 creditsStarter+
Recent News FeedGET /news/recent1 creditAll
Financial ReportsGET /companies/{uid}/reports5 creditsStarter+
Company ComparisonPOST /companies/compare5 creditsStarter+

Tier Allowances

Each plan includes a monthly credit allowance. Credits reset at the start of every billing period and do not roll over.

TierPriceIncluded CreditsOverage
FreeCHF 0/mo1,000Blocked
StarterCHF 99/mo50,0000.3¢/credit
ProfessionalCHF 399/mo250,0000.2¢/credit
EnterpriseCustom1,000,000+0.1¢/credit

Need more credits? Compare plans or contact sales for a custom Enterprise arrangement.

Overage Billing

When a paid tier exhausts its included credits, additional credits are automatically consumed from an overage pool. Overage is billed at the end of the billing period.

text
Overage example (Starter tier):
Monthly included credits: 50,000
Credits used this month:  52,500
Overage credits:           2,500
Overage rate:          CHF 0.003/credit
Overage charge:        CHF 7.50
Billed at period end on top of the CHF 99/mo subscription.

The Free tier does not support overage — requests are blocked once the 1,000 credit allowance is exhausted. Upgrade to Starter or above to enable overage billing.

Tracking Your Usage

Monitor credit consumption via the API, response headers, or the Usage dashboard.

Credit Balance

Bash
# Check current credit balance
curl "https://api.vynco.ch/v1/credits/balance" \
  -H "Authorization: Bearer vc_live_abc123..."
JSON
{
  "balance": 48750,
  "tier": "starter",
  "periodStart": "2026-03-01T00:00:00Z",
  "periodEnd": "2026-03-31T23:59:59Z"
}

Usage Breakdown

Bash
# Get usage breakdown by operation
curl "https://api.vynco.ch/v1/credits/usage" \
  -H "Authorization: Bearer vc_live_abc123..."
JSON
{
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-31T23:59:59Z"
  },
  "totalUsed": 1250,
  "breakdown": [
    { "operation": "CompanySearch",   "count": 840, "creditsUsed": 840 },
    { "operation": "EnrichedProfile", "count": 62,  "creditsUsed": 310 },
    { "operation": "DossierSummary",  "count": 5,   "creditsUsed": 100 }
  ]
}

Per-Response Headers

http
# Credits are also returned in every response header
HTTP/2 200
X-Credits-Used: 5
X-Credits-Remaining: 48750
X-Rate-Limit-Limit: 60
X-Request-Id: req_abc123
X-Data-Source: Zefix

Best Practices

Follow these guidelines to make the most of your credit allowance.

Cache company lookups

Company data changes infrequently. Cache GET /companies/{uid} responses for at least 24 hours to avoid redundant credit spend.

Use search before lookup

A search (1 credit) returns UIDs in bulk. Only fetch enriched profiles (5 credits) for companies you actually need.

Monitor X-Credits-Remaining

Log the X-Credits-Remaining header in every response. Alert your team when the balance drops below a threshold.

Choose the right dossier level

Use level: summary (20 cr) for quick screening. Reserve level: comprehensive (100 cr) for final due diligence.

Poll /credits/usage regularly

Set up a daily cron job that calls GET /credits/usage and reports per-operation totals to your team.

Use test keys in CI

vc_test_* keys run in sandbox mode and do not consume credits. Use them in automated tests and staging environments.

Frequently Asked Questions

Common questions about the credit system.