> ## Documentation Index
> Fetch the complete documentation index at: https://docs.creatordb.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Fractional Calls

> Request only the fields you need and pay proportionally.

<Note>
  You must enable **Fractional Calls** on your API key. Otherwise, requests that include a `fields` parameter return a `400` error (`FractionalCallsNotEnabled`). Full-response calls (without `fields`) always work. Contact your account manager to enable fractional calls.
</Note>

## Overview

By default, a CreatorDB data endpoint returns the full response and charges a fixed **full-bundle price**. With **fractional calls**, you can request only the fields or items you need and pay **proportionally**. You are **never charged more than the full-bundle price**.

<Note>
  * `search` accepts `fields`, but with a different shape and billing model. It is used for per-result enrichment, not for selecting search's own return fields. See [Search enrichment](#search-enrichment).

  * `performance-history` does not accept `fields` at all; it's priced by time range. See [Range endpoint: performance-history](#range-endpoint-performance-history).

  * `nls` does not yet support fractional field selection in this release. See the [NLS endpoint reference](/api-reference/ai-search/search-creators-by-prompt) for its current token-based billing.
</Note>

You opt in per request by adding a `fields` parameter to the request body. When `fields` is omitted, you get the full response at the standard price, exactly as before.

## How it works

Fractional endpoints accept a `POST` request with the creator identifier and an optional `fields` parameter in the JSON body.

```bash theme={null}
curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
  --header 'Content-Type: application/json' \
  --header 'api-key: YOUR_API_KEY' \
  --data '{
    "channelId": "UCX6OQ3DkcsbYNE6H8uQQuVA",
    "fields": ["displayName", "country", "totalSubscribers"]
  }'
```

The response contains only the requested fields, and you are charged according to the endpoint's pricing model. Costs for field-list and per-item endpoints are capped at the endpoint's full price. For details, see the sections below.

## The `fields` parameter by endpoint type

Different endpoints select data in different ways. See the sections below for the shape each endpoint expects.

### Field-list endpoints: `profile`, `performance`, `audience`, `contact`

Pass an **array of field names**. You pay the **sum of the requested fields' costs**. Costs are capped at the endpoint's full price.

```json theme={null}
{ "channelId": "UC...", "fields": ["displayName", "country"] }
```

* Each field has a small per-field cost (see the per-endpoint reference for the exact list).
* Requesting many fields can never cost more than the full-bundle price, which is a hard ceiling.
* `fields: []` (empty array) or omitting `fields` returns the **full response** at the full-bundle price.
* Passing an **object** instead of an array returns a `400` validation error.

### Per-item endpoints: `content-detail`, `sponsorship`

Pass an **object** mapping an array field to the number of items you want. You pay **per item returned**, capped at the endpoint's full price.

```json theme={null}
{ "channelId": "UC...", "fields": { "recentVideos": 5 } }
```

* `content-detail`: `0.1` credits per content item (video, short, image, or reel).
* `sponsorship`: `0.5` credits per sponsoring brand returned. Available for YouTube and Instagram only. TikTok has no `sponsorship` endpoint.
* `fields: {}` (empty object) or omitting `fields` returns **all items** at the full-bundle price.
* Passing an **array** instead of an object (including the legacy `["recentVideos:5"]` form) returns a `400` validation error.

### Range endpoint: `performance-history`

`performance-history` does not accept a `fields` parameter. Passing one in any shape returns a `400` validation error. Pricing is determined solely by the **time range** you request via `pastDayRange`. For details, see [API Credit Usage](/api-v3/api-credit-usage).

### Search enrichment: `search`

On `/{platform}/search`, you can enrich each result with data from other endpoints by passing a `fields` object keyed by endpoint name. Each enrichment is charged **per result returned**, using that endpoint's own pricing rules.

```json theme={null}
{
  "filters": [ { "filterName": "totalSubscribers", "op": ">", "value": 1000000 } ],
  "fields": { "profile": ["country"], "content-detail": { "recentVideos": 3 } }
}
```

* Endpoint keys must be **bare names** such as `profile`, not platform-prefixed names such as `youtube/profile`. The platform is implicit from the search URL, and any key containing a `/` returns a `400` validation error.
* On search, `fields` is used solely for enrichment. You cannot use it to subset search's own return fields. All standard search fields are always included at the base search cost.

Enrichment cost scales with the number of results. Use a smaller`pageSize`to control spend.

## The no-gotcha cap

For every fractional endpoint, the price you pay is **capped at the full-bundle price**. Enumerating many fields or requesting many items never costs more than requesting the full response. Fractional calls only ever save you credits. They never cost extra.

## Full response (no `fields`)

To get the full response at the standard price, omit `fields` entirely, or pass the empty form (`fields: []` for field-list endpoints, `fields: {}` for per-item endpoints). All of these are equivalent and bill at the full-bundle price.

## Examples

<CodeGroup>
  ```bash Profile (2 fields) theme={null}
  curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "channelId": "UC...", "fields": ["displayName", "country"] }'
  # Cost: sum of the two field costs (well under the 2-credit full price)
  ```

  ```bash Content detail (5 recent videos) theme={null}
  curl -X POST "https://apiv3.creatordb.app/youtube/content-detail" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "channelId": "UC...", "fields": { "recentVideos": 5 } }'
  # Cost: 0.1 x 5 = 0.5 credits (full bundle would be 3)
  ```

  ```bash Full response (no fields) theme={null}
  curl -X POST "https://apiv3.creatordb.app/youtube/profile" \
    --header 'Content-Type: application/json' \
    --header 'api-key: YOUR_API_KEY' \
    --data '{ "channelId": "UC..." }'
  # Cost: 2 credits (full-bundle price)
  ```
</CodeGroup>

## Credit costs

See [API Credit Usage](/api-v3/api-credit-usage) for each endpoint's full-bundle price and the per-field or per-item costs.