---
title: "Follow a market"
method: POST
path: "/api/v1/following"
tags: ["Authenticated integrations"]
---

# Follow a market

`POST /api/v1/following`

## Request

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

Follow a market for this account, the same as following it in the Kunkafa app: the plan's Following count, the replacement window and restores apply exactly. Filling a free place is immediate. A follow that would replace a followed market is refused with follow_replacement_confirmation unless confirmReplacement is true; ask the user first. Idempotent: following a followed market returns action unchanged. Pro and Publisher REST.

## Request body

- IntegrationFollowRequest
  - `market` string, required: Published English-name market slug returned by authorized discovery.
  - `confirmReplacement` boolean: Set only after the user agreed: this follow replaces a followed market and starts the replacement window.

## Response `200`

The change and the account's following after it.

- IntegrationFollowingResponse: The change and the account's following after it. The Kunkafa app shows the same list immediately.
  - `data` IntegrationFollowingChange, required
    - `market` string, required: Published English-name market slug returned by authorized discovery.
    - `action` 'followed' | 'unfollowed' | 'unchanged', required
    - `nextChangeAllowedAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
  - `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.
  - `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.
- `409`: Conflict with the account state: the plan's Following count is reached, the market has no live data, or a replacement needs confirmation.
- `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)