---
title: "Outlooks"
method: POST
path: "/api/v1/outlooks"
tags: ["Authenticated integrations"]
---

# Outlooks

`POST /api/v1/outlooks`

## Request

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

Read a selection of one authorized market's current forecasts, the same as the MCP get_outlooks tool: choose durations by label or by range (minDuration, maxDuration, maxDurationExclusive), and optionally a direction, probability bounds (Kunkafa's confidence) and target-distance bounds. One call returns at most 6 durations and 72 forecasts; a broader request returns request_too_broad with the matching counts and available durations. Historical performance and selected past results are read with their own operations. Each distinct selection is one disclosure against the allowance; repeating the same selection on unchanged data is not charged again. The latest eligible private-data request becomes the account's active integration session; it never interrupts the Kunkafa app. Pro and Publisher REST.

## Request body

- IntegrationOutlooksRequest: One market and at least one duration selector (durations, or minDuration and/or maxDuration). One call returns at most 6 durations and 72 forecasts after filters; a broader request returns request_too_broad.
  - `market` string, required: Published English-name market slug returned by authorized discovery.
  - `durations` string[]: Exact duration labels from the market list, for example ["1 hour", "6 hours"]. Use either durations or a range.
  - `minDuration` string: Shortest duration to include, for example "1 hour".
  - `maxDuration` string: Longest duration to include, for example "1 day".
  - `maxDurationExclusive` boolean: true for "less than maxDuration"; by default maxDuration is included.
  - `direction` 'up' | 'down' | 'both'
  - `minProbabilityPercent` number: Only forecasts whose probability (Kunkafa's confidence) is at least this.
  - `maxProbabilityPercent` number
  - `minTargetPercent` number: Only targets at least this far from the reference price, in percent, either direction.
  - `maxTargetPercent` number

## Response `200`

Selected forecasts; 20-second request timeout.

- IntegrationOutlooksResponse: One market's selected forecasts. Each distinct selection is one disclosure against the allowance; repeating the same selection on unchanged data is not charged again.
  - `data` IntegrationOutlookSelection, required: The requested selection of one market's current forecasts. Historical performance and selected past results are read with their own operations.
    - `market` string, required: Published English-name market slug returned by authorized discovery.
    - `name` string, required
    - `url` string, uri, required
    - `sourceAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
    - `selection` object, required
      - `durations` string[], required
      - `direction` 'up' | 'down' | 'both', required
      - `minProbabilityPercent` number, required
      - `maxProbabilityPercent` number, required
      - `minTargetPercent` number, required
      - `maxTargetPercent` number, nullable, required
    - `availableDurations` string[], required: Durations of this market that have forecasts now; a duration with none is left out.
    - `forecasts` IntegrationSelectedSource[], required
      - `duration` string, required
      - `sourceAt` string, date-time, required: ISO 8601 UTC timestamp supplied by Kunkafa.
      - `forecastAt` string, date-time: ISO 8601 UTC timestamp supplied by Kunkafa.
      - `referencePrice` number, required
      - `outputs` IntegrationSelectedOutput[], required
        - `direction` 'up' | 'down', required
        - `movePercent` number, required
        - `probabilityPercent` number, required
      - `label` string, required: Names the source within its duration (A, B, C…): forecasts made together. Sources are read side by side, never merged.
    - `counts` object, required
      - `forecasts` integer, required
      - `withoutProbability` integer, required
    - `withoutForecasts` object[]: Asked-for durations with no forecasts: none_now (none at the moment) or no_match (none match the filters). Left out when every duration has forecasts.
      - `duration` string, required
      - `reason` 'none_now' | 'no_match', required
  - `fieldGuide` IntegrationOutlookFieldGuide, required
    - `probabilityPercent` string, required
    - `movePercent` string, required
    - `referencePrice` string, required
    - `sourceAt` string, required
    - `forecastAt` string, required
    - `counts` string, required
    - `interpretation` string, required
    - `more` string, required
    - `label` string, required
    - `withoutForecasts` string
  - `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.
- `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)