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.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.-
searchacceptsfields, 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. -
performance-historydoes not acceptfieldsat all; it’s priced by time range. See Range endpoint: performance-history. -
nlsdoes not yet support fractional field selection in this release. See the NLS endpoint reference for its current token-based billing.
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 aPOST request with the creator identifier and an optional fields parameter in the JSON body.
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.
- 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 omittingfieldsreturns the full response at the full-bundle price.- Passing an object instead of an array returns a
400validation 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.
content-detail:0.1credits per content item (video, short, image, or reel).sponsorship:0.5credits per sponsoring brand returned. Available for YouTube and Instagram only. TikTok has nosponsorshipendpoint.fields: {}(empty object) or omittingfieldsreturns all items at the full-bundle price.- Passing an array instead of an object (including the legacy
["recentVideos:5"]form) returns a400validation 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.
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.
- Endpoint keys must be bare names such as
profile, not platform-prefixed names such asyoutube/profile. The platform is implicit from the search URL, and any key containing a/returns a400validation error. - On search,
fieldsis 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.
pageSizeto 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.