KOLens Usage API
The Usage API from KOLens — 3 operation(s) for usage.
The Usage API from KOLens — 3 operation(s) for usage.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/kolens-ai:kolens-ai-usage-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: KOLens Usage API
description: KOLens — TikTok KOL Intelligence API. Search keywords, extract KOL profiles, collect contact info, export reports.
version: 1.0.0
tags:
- name: Usage
paths:
/api/usage/daily:
get:
tags:
- Usage
summary: Daily Usage
description: Per-day rollup of credits charged + jobs run for the calling user.
operationId: daily_usage_api_usage_daily_get
security:
- HTTPBearer: []
parameters:
- name: days
in: query
required: false
schema:
type: integer
maximum: 365
minimum: 1
description: How many trailing days to include
default: 30
title: Days
description: How many trailing days to include
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Daily Usage Api Usage Daily Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/usage/jobs:
get:
tags:
- Usage
summary: Usage Jobs
description: List the calling user's completed jobs with what each one cost.
operationId: usage_jobs_api_usage_jobs_get
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 500
minimum: 1
default: 50
title: Limit
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Offset
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: object
title: Response Usage Jobs Api Usage Jobs Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/api/usage/ledger:
get:
tags:
- Usage
summary: Usage Ledger
description: 'Unified credit history — debits (scrapes) AND credits (top-ups).
This is the feed the credits page renders. Before this endpoint the
page only ever showed debits, so a user could watch their balance go
down but never saw the matching ``+N credits`` when they bought a
pack. We merge:
1. Debits — completed jobs that actually charged credits
(``credits_charged`` > 0) from our Postgres ``search_jobs``.
2. Credits — personal top-ups from the Supabase ``credit_purchases``
table (via ``CreditsService.list_purchases``), the same rows the
Orders page shows.
Both are sorted newest-first and capped at ``limit``. If Supabase is
unreachable / unconfigured (local dev, CI) the credit side is simply
empty and the feed degrades to debits-only — never an error.'
operationId: usage_ledger_api_usage_ledger_get
security:
- HTTPBearer: []
parameters:
- name: limit
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 50
title: Limit
- name: x-kolens-user-id
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Kolens-User-Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LedgerOut'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
LedgerOut:
properties:
user_id:
type: string
title: User Id
limit:
type: integer
title: Limit
entries:
items:
$ref: '#/components/schemas/LedgerEntry'
type: array
title: Entries
type: object
required:
- user_id
- limit
title: LedgerOut
LedgerEntry:
properties:
id:
type: string
title: Id
kind:
type: string
enum:
- debit
- credit
title: Kind
delta:
type: number
title: Delta
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
label:
type: string
title: Label
default: ''
job_id:
anyOf:
- type: string
- type: 'null'
title: Job Id
status:
anyOf:
- type: string
- type: 'null'
title: Status
data_source:
anyOf:
- type: string
- type: 'null'
title: Data Source
source:
anyOf:
- type: object
- type: 'null'
title: Source
amount_cents:
anyOf:
- type: integer
- type: 'null'
title: Amount Cents
stripe_session_id:
anyOf:
- type: string
- type: 'null'
title: Stripe Session Id
type: object
required:
- id
- kind
- delta
title: LedgerEntry
description: "One row in the unified credit history.\n\n``kind`` discriminates the two event sources:\n - ``\"debit\"`` — a scrape job that charged credits (from search_jobs).\n - ``\"credit\"`` — a credit top-up / purchase (from credit_purchases).\n\n``delta`` is signed: negative for debits, positive for credits, so a\nclient can render \"−5\" / \"+200\" without re-deriving the sign from\n``kind``. ``created_at`` is the ISO timestamp the event is sorted by."
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
HTTPBearer:
type: http
scheme: bearer