---
title: "Usage"
method: GET
path: "/api/v1/usage"
tags: ["Authenticated integrations"]
---

# Usage

`GET /api/v1/usage`

## Request

- Base URL: `https://kunkafa.com`
- URL: `https://kunkafa.com/api/v1/usage`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://kunkafa.com/oauth/authorize`, token URL `https://kunkafa.com/oauth/token`, scopes: `usage:read`)

Read shared account allowances, what one outlook call can return, and a paginated permitted-market list. Pro and Publisher REST. No summary charge or change to the integration session; request protection still applies.

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Complete response; 20-second request timeout and 128 KiB response ceiling.

- IntegrationUsageResponse
  - `data` object, required
    - `permittedMarkets` IntegrationMarketSlug[], required
    - `outlookLimits` object, required: What one get_outlooks call can return.
      - `marketsPerCall` unknown, required
      - `maxDurations` unknown, required
      - `maxForecasts` unknown, required
    - `connection` object, required: This connection's permissions and expiry. An MCP (OAuth) connection stays connected while used: it expires after idleDays without use, at most one year after it was approved. A reconnect from the same app replaces it without using another connection.
      - `kind` 'oauth' | 'personal_token', required
      - `permissions` string[], required
      - `expiresAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
      - `staysConnectedWhileUsed` unknown
      - `idleDays` unknown
      - `canFollow` boolean, required: Whether this connection may follow and unfollow markets (the following:write permission).
      - `howToAllowFollowing` string: Present only when canFollow is false: how the user allows following for this connection.
  - `following` IntegrationFollowing, required: What the account follows and can still follow. Following decides which markets can be read; it happens in the Kunkafa app.
    - `followed` integer, required: Markets on the account's following list, as the app counts them.
    - `followLimit` integer, nullable, required: The plan's Following count; null when the account reads every market.
    - `canFollowMore` integer, nullable, required: How many more markets can be followed; null when the account reads every market.
    - `readsEveryMarket` boolean, required
    - `message` string, required: Plain explanation for the user, including for accounts that read every market.
    - `followInApp` string, uri, required: Where the user follows markets in the Kunkafa app.
    - `otherMarkets` object[], required: Catalogue markets the account does not follow, by English name, sorted by name; at most 100 (otherMarketsTotal gives the full count). Any market can still be followed by its slug.
      - `market` string, required: Published English-name market slug returned by authorized discovery.
      - `name` string, required
    - `otherMarketsTotal` integer, required: How many catalogue markets the account does not follow.
    - `canFollow` boolean: Whether this connection may follow and unfollow markets.
    - `howToAllowFollowing` string: Present when canFollow is false.
  - `usage` IntegrationUsage, required
    - `calculatedAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
    - `tier` 'free' | 'starter' | 'core' | 'pro' | 'publisher', required
    - `requests` object, required: Steady request rate with bounded burst capacity; metadata and repeated summaries still count toward request protection.
      - `perMinute` integer, required
      - `burst` integer, required
      - `remaining` integer, required
      - `nextRequestAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
    - `concurrency` object, required: Private requests that can run at the same time. Requests from one connection run side by side up to this limit (the plan burst); a request from another connection waits until they finish.
      - `limit` integer, required
      - `remaining` integer, required
      - `nextRequestAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
    - `windows` IntegrationWindowUsage[], required
      - `period` 'day' | 'week' | 'month', required
      - `used` integer, required
      - `limit` integer, required
      - `remaining` integer, required
      - `nextCapacityAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
      - `notice` unknown, required
      - `noticeId` string, nullable, required
    - `adjustment` object: An owner-approved account allowance increase. A null expiration is permanent until changed. Usage is never reset; market access and credential eligibility still follow the current plan.
      - `expiresAt` string, date-time, nullable, required
  - `notices` IntegrationNotice[], required
    - `id` string, required
    - `period` 'day' | 'week' | 'month', required
    - `kind` 'approaching_limit' | 'limit_reached', required
    - `message` string, required
    - `used` integer, required
    - `limit` integer, required
    - `remaining` integer, required
    - `nextCapacityAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
  - `page` IntegrationPage, required: Follow nextCursor until null. Cursors are invalidated by relevant access or market-list changes; restart without a cursor.
    - `total` integer, required
    - `returned` integer, required
    - `nextCursor` string, nullable, required
  - `dataUse` string, required: Use restriction on every reply: data collection is prohibited; the data may not be collected, saved, stored, exported or compiled, or used to train, retrain, fine-tune or distil any model.

## Other responses

- `400`: Invalid fields, an unknown or missing duration, a request broader than one call returns, or an invalid pagination cursor.
- `401`: Missing, invalid, expired or revoked credentials.
- `403`: Account, permission, plan or market is not authorized.
- `404`: Unknown API operation or route.
- `405`: HTTP method not supported.
- `413`: Request body exceeds the 16 KiB limit.
- `415`: Use application/json for request bodies.
- `429`: Request, concurrency, traffic or rolling summary limit. No partial private delivery or new disclosure charges.
- `503`: Temporary access/accounting failure or unavailable data. This is not exhausted allowance.

---

[API](https://skmtc.dev/kunkafa/apis/kunkafa-public-data-and-integrations.md) · [All operations](https://skmtc.dev/kunkafa/apis/kunkafa-public-data-and-integrations/llms.txt) · [OpenAPI document](https://skmtc.dev/kunkafa/apis/kunkafa-public-data-and-integrations/revisions/8217b961f423?raw)