> ## Documentation Index > Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt > Use this file to discover all available pages before exploring further. # Pinterest trends by country > Native Pinterest Trends rankings for 23 supported countries. Choose growing, seasonal, top_monthly or top_yearly; native include/exclude filters apply before the requested depth of 1–50. Ireland reads GB+IE, Australia/New Zealand read AU+NZ, and GB reads its own market. Each row preserves rank, relative 0–100 search index, fractional weekly/monthly/yearly changes, seasonality and the source data date. 100.01 is Pinterest’s capped near-zero-baseline change signal. Nonempty uncached results cost 10 credits; a confirmed empty ranking is uncharged 404, and errors/cache hits/idempotent replays are free. Exact repeats are cached six hours. Anonymous public source, without account credentials or an upstream availability guarantee. Get the native **growing, seasonal, top monthly or top yearly** Pinterest ranking. The default is US, growing, 25 terms; `limit` accepts 1–50. `include` keeps terms containing a listed keyword, and `exclude` removes matching terms. Each accepts up to ten comma-separated keywords. These are native source filters applied before depth, not a filter over a previously truncated top-N page. Supported countries: AR, AU, BR, CA, CO, DE, EG, ES, FR, GB, ID, IE, IN, IT, KR, MX, MY, NZ, PH, SA, TH, TR and US. Codes are case-insensitive. Ireland uses the combined **GB+IE** market; Australia and New Zealand use **AU+NZ**. Great Britain uses **GB**. `country` identifies the requested country and `market` identifies the actual source list. Each term has its native rank, a relative `search_index` from 0–100, `weekly_change`, `monthly_change`, `yearly_change`, `seasonality`, a Trends link and `as_of`. A change of `0.3` means +30%; `100.01` is the source's capped signal for a near-zero prior baseline, not an exact growth measurement. The index is normalized within this response and is not an absolute search count. The source's weekly `as_of` date is preserved; it is not replaced with request time. A nonempty uncached request costs **10 credits**, independent of depth. Use `X-Max-Credits: 10`. Confirmed empty lists return uncharged **404**; upstream failures also consume no customer credits. Exact repeats use a **six-hour cache** at zero credits, and successful idempotent replay is free. `Cache-Control: no-cache` requests a fresh source read. The adapter uses Pinterest's anonymous public Trends source, without Pinterest cookies or account credentials. Its shared request limit is ten source reads per minute. Source throttling or invalid responses fail without charging; this is not a Pinterest partner API or a guarantee of uninterrupted upstream availability. ## OpenAPI ````yaml GET /pinterest/trends openapi: 3.1.0 info: title: SocialQuery API version: '2026-10-09' description: >- Documented requests for public-source records. Inspect accepted inputs and credit amounts, then verify the selected operation before integrating preview coverage. servers: - url: https://socialquery.dev/v1 security: - apiKey: [] paths: /pinterest/trends: get: tags: - Pinterest summary: Pinterest Trends description: >- Native Pinterest Trends rankings for 23 supported countries. Choose growing, seasonal, top_monthly or top_yearly; native include/exclude filters apply before the requested depth of 1–50. Ireland reads GB+IE, Australia/New Zealand read AU+NZ, and GB reads its own market. Each row preserves rank, relative 0–100 search index, fractional weekly/monthly/yearly changes, seasonality and the source data date. 100.01 is Pinterest’s capped near-zero-baseline change signal. Nonempty uncached results cost 10 credits; a confirmed empty ranking is uncharged 404, and errors/cache hits/idempotent replays are free. Exact repeats are cached six hours. Anonymous public source, without account credentials or an upstream availability guarantee. operationId: get_pinterest_trends parameters: - name: country in: query required: false example: DE schema: type: string description: >- Case-insensitive ISO country. Default US. IE maps to GB+IE; AU and NZ map to AU+NZ. GB remains separate. - name: type in: query required: false example: growing schema: type: string enum: - growing - seasonal - top_monthly - top_yearly - name: limit in: query required: false example: 5 schema: type: integer minimum: 1 maximum: 50 default: 25 - name: include in: query required: false schema: type: string description: >- One to ten comma-separated keywords, each at most 100 characters. Native matching occurs before the requested depth. - name: exclude in: query required: false schema: type: string description: >- One to ten comma-separated keywords, each at most 100 characters. Native matching occurs before the requested depth. - name: Cache-Control in: header required: false example: no-cache schema: type: string - name: Idempotency-Key in: header required: false example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c schema: type: string - name: X-Max-Credits in: header required: false description: >- Optional nonnegative integer cap on the maximum request hold. A live request whose hold exceeds this cap returns 422 CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the requested limit; cache hits and successful idempotent replays cost zero. schema: type: integer minimum: 0 responses: '200': description: >- Native Pinterest Trends rankings for 23 supported countries. Choose growing, seasonal, top_monthly or top_yearly; native include/exclude filters apply before the requested depth of 1–50. Ireland reads GB+IE, Australia/New Zealand read AU+NZ, and GB reads its own market. Each row preserves rank, relative 0–100 search index, fractional weekly/monthly/yearly changes, seasonality and the source data date. 100.01 is Pinterest’s capped near-zero-baseline change signal. Nonempty uncached results cost 10 credits; a confirmed empty ranking is uncharged 404, and errors/cache hits/idempotent replays are free. Exact repeats are cached six hours. Anonymous public source, without account credentials or an upstream availability guarantee. content: application/json: schema: allOf: - $ref: '#/components/schemas/SocialQueryResponse' - type: object properties: data: type: object properties: items: type: array minItems: 1 maxItems: 50 items: type: object properties: rank: type: integer minimum: 1 maximum: 50 term: type: string country: type: string market: type: string type: type: string enum: - growing - seasonal - top_monthly - top_yearly search_index: type: number minimum: 0 maximum: 100 weekly_change: type: number minimum: -1 maximum: 100.01 monthly_change: type: number minimum: -1 maximum: 100.01 yearly_change: type: number minimum: -1 maximum: 100.01 seasonality: type: number minimum: 0 maximum: 1 url: type: string format: uri as_of: type: string format: date required: - rank - term - country - market - type - search_index - weekly_change - monthly_change - yearly_change - seasonality - url - as_of additionalProperties: false returned_count: type: integer minimum: 1 maximum: 50 country: type: string market: type: string type: type: string enum: - growing - seasonal - top_monthly - top_yearly as_of: type: string format: date source: type: string format: uri coverage_note: type: string required: - items - returned_count - country - market - type - as_of - source - coverage_note additionalProperties: false required: - data '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '402': $ref: '#/components/responses/Error402' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '405': $ref: '#/components/responses/Error405' '409': $ref: '#/components/responses/Error409' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '502': $ref: '#/components/responses/Error502' '503': $ref: '#/components/responses/Error503' '504': $ref: '#/components/responses/Error504' components: schemas: SocialQueryResponse: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - data properties: success: type: boolean const: true platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean data: type: object additionalProperties: true description: >- The selected operation determines the resource fields in this object. Source data can omit a metric or report it as null. SocialQueryError: type: object required: - success - platform - endpoint - credits_used - credits_remaining - request_id - cached - error properties: success: type: boolean const: false platform: type: string endpoint: type: string credits_used: type: integer minimum: 0 credits_remaining: type: - integer - 'null' request_id: type: string cached: type: boolean error: type: object required: - code - type - message - status - doc_url properties: code: type: string type: type: string message: type: string status: type: integer doc_url: type: string format: uri responses: Error400: description: Upstream rejected the request. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error401: description: Missing, expired, invalid, or revoked API key. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error402: description: Insufficient SocialQuery credits. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error403: description: Key scope or provider policy denied access. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error404: description: Endpoint or upstream resource not found. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error405: description: HTTP method is not supported. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error409: description: Idempotency conflict or request in progress. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error422: description: Invalid parameters. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error429: description: Request limit reached. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error500: description: Request processing failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error502: description: Upstream service failed. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error503: description: Provider or required service is unavailable. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' Error504: description: Upstream service timed out. headers: X-Request-Id: schema: type: string X-Credits-Used: schema: type: integer X-Credits-Remaining: schema: type: string X-Cache: schema: type: string enum: - HIT - MISS - BYPASS content: application/json: schema: $ref: '#/components/schemas/SocialQueryError' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.