> ## Documentation Index > Fetch the complete documentation index at: https://docs.refmatter.com/llms.txt > Use this file to discover all available pages before exploring further. # Search a platform > Costs 1 credit for a live page or the first serving of a stored page with at least one row; empty pages, errors and repeats within maxAge are free. Instagram and TikTok publish no anonymous search and answer 422 with a hint. Meta Ad Library answers about advertisers only, one page of up to 15, with no cursor. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/search openapi: 3.1.0 info: title: Refmatter API version: 0.1.0 description: >- Public social data API: one request turns a TikTok, Instagram, YouTube or Meta Ad Library link into structured data; import it to keep verified media, a transcript and provenance. servers: - url: https://api.refmatter.com security: - bearerApiKey: [] tags: - name: workspaces x-group: Workspaces description: Manage workspaces and review their usage. - name: imports x-group: Imports description: Start imports from source URLs and check their progress. - name: urls x-group: URLs description: Identify the platform and object represented by a social URL. - name: items x-group: Items description: List and look up items from supported platforms. - name: accounts x-group: Accounts description: Look up accounts and retrieve their current data. - name: comments x-group: Comments description: List comments for supported items. - name: search x-group: Search description: Search supported platforms for items or accounts. - name: references x-group: References description: Manage saved references and their transcripts and media. - name: media x-group: Media description: Create short-lived access to stored media. - name: sourceRoutes x-group: Sources description: List the supported platforms and objects with their limits. paths: /v1/search: get: tags: - search summary: Search a platform description: >- Costs 1 credit for a live page or the first serving of a stored page with at least one row; empty pages, errors and repeats within maxAge are free. Instagram and TikTok publish no anonymous search and answer 422 with a hint. Meta Ad Library answers about advertisers only, one page of up to 15, with no cursor. operationId: search parameters: - name: platform in: query required: true description: Which platform to search schema: enum: - youtube - meta_ad_library - name: q in: query required: false description: Search phrase, one to 200 characters schema: type: string minLength: 1 maxLength: 200 - name: type in: query required: false description: Result kind; Meta Ad Library accepts accounts only schema: enum: - items - accounts - name: uploadDate in: query required: false description: Item upload date filter; YouTube only schema: enum: - today - week - month - year - name: duration in: query required: false description: Item duration filter; YouTube only schema: enum: - short - medium - long - name: sort in: query required: false description: Search ordering; YouTube only schema: enum: - relevance - popular default: relevance - name: country in: query required: false description: ALL, or a two-letter country code; Meta Ad Library only schema: type: string pattern: ^(ALL|[A-Za-z]{2})$ default: ALL - name: cursor in: query required: false description: Opaque cursor from a previous page schema: type: string - name: maxAge in: query required: false description: How fresh a stored page may be; default 15m schema: type: string pattern: ^(0|[1-9][0-9]{0,5}[mhd])$ default: 15m responses: '200': description: One page of search results headers: Refmatter-Credits-Charged: description: Credits charged schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: Credits the workspace has left after this response schema: type: integer Server-Timing: description: Lookup phase durations schema: type: string Cache-Control: description: A lookup answer is never stored by a cache on the way schema: type: string const: no-store content: application/json: schema: oneOf: - $ref: '#/components/schemas/ItemSummaryList' - $ref: '#/components/schemas/AccountList' '400': description: Invalid request headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Authentication required headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '402': description: The workspace has no credits left headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Action not permitted headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Resource not found headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '410': description: Source content removed headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '422': description: Request cannot be fulfilled by the current source contract headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer Retry-After: description: Whole seconds until another attempt is likely to succeed schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '500': description: Internal error headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '502': description: Source failed or changed headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '503': description: Service or dependency unavailable headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '504': description: Source timed out headers: Refmatter-Credits-Charged: description: Credits charged; every error is free schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: >- Credits the workspace has left; absent when the request named no workspace schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' security: - bearerApiKey: [] components: schemas: ItemSummaryList: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: object: type: string const: list data: maxItems: 100 type: array items: type: object properties: object: type: string const: item_summary id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ platform: type: string enum: - youtube - tiktok - instagram - meta_ad_library kind: type: string enum: - video - short - image - carousel - ad url: type: string minLength: 1 maxLength: 2048 author: anyOf: - type: object properties: object: type: string const: account id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ platform: type: string enum: - youtube - tiktok - instagram - meta_ad_library handle: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' name: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' required: - object - id - platform - handle - name - url additionalProperties: false - type: 'null' title: anyOf: - type: string minLength: 0 maxLength: 1000 - type: 'null' text: anyOf: - type: string minLength: 0 maxLength: 10000 - type: 'null' publishedAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' publishedText: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' durationMs: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' stats: type: object properties: views: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' likes: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' comments: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' shares: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' saves: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - views - likes - comments - shares - saves additionalProperties: false viewsApproximate: type: - boolean - 'null' thumbnails: maxItems: 64 type: array items: type: object properties: url: type: string minLength: 1 maxLength: 2048 width: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' expiresAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' required: - url - width - height - expiresAt additionalProperties: false live: type: - boolean - 'null' ad: anyOf: - type: object properties: archiveId: type: string minLength: 1 maxLength: 64 pageId: type: string minLength: 1 maxLength: 32 pageName: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' active: type: - boolean - 'null' startedAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' endedAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' collationId: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' collationCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' displayFormat: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' platforms: maxItems: 16 type: array items: type: string minLength: 1 maxLength: 64 mediaKind: type: string enum: - video - image - carousel - text spend: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' impressions: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' reach: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' currency: anyOf: - type: string minLength: 1 maxLength: 16 - type: 'null' required: - archiveId - pageId - pageName - active - startedAt - endedAt - collationId - collationCount - displayFormat - platforms - mediaKind - spend - impressions - reach - currency additionalProperties: false - type: 'null' required: - object - id - platform - kind - url - author - title - text - publishedAt - publishedText - durationMs - stats - viewsApproximate - thumbnails - live - ad additionalProperties: false page: type: object properties: nextCursor: anyOf: - type: string minLength: 16 maxLength: 2048 pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ - type: 'null' hasMore: type: boolean required: - nextCursor - hasMore additionalProperties: false total: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' totalApproximate: type: - boolean - 'null' account: anyOf: - type: object properties: object: type: string const: account id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ platform: type: string enum: - youtube - tiktok - instagram - meta_ad_library handle: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' name: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' required: - object - id - platform - handle - name - url additionalProperties: false - type: 'null' observedAt: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ cached: type: boolean usage: type: object properties: creditsCharged: type: integer minimum: 0 maximum: 9007199254740991 lines: maxItems: 8 type: array items: type: object properties: part: type: string enum: - fetch credits: type: integer minimum: 1 maximum: 9007199254740991 required: - part - credits additionalProperties: false required: - creditsCharged - lines additionalProperties: false required: - object - data - page - total - totalApproximate - account - observedAt - cached - usage additionalProperties: false AccountList: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: object: type: string const: list data: maxItems: 100 type: array items: type: object properties: object: type: string const: account id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ platform: type: string enum: - youtube - tiktok - instagram - meta_ad_library handle: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' name: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' description: anyOf: - type: string minLength: 0 maxLength: 5000 - type: 'null' avatar: maxItems: 64 type: array items: type: object properties: url: type: string minLength: 1 maxLength: 2048 width: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' expiresAt: anyOf: - type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ - type: 'null' required: - url - width - height - expiresAt additionalProperties: false verified: type: - boolean - 'null' stats: type: object properties: followers: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - followers additionalProperties: false meta_ad_library: anyOf: - type: object properties: category: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' likes: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' instagramHandle: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' instagramFollowers: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' instagramVerified: type: - boolean - 'null' pageDeleted: type: - boolean - 'null' required: - category - likes - instagramHandle - instagramFollowers - instagramVerified - pageDeleted additionalProperties: false - type: 'null' required: - object - id - platform - handle - name - url - description - avatar - verified - stats - meta_ad_library additionalProperties: false page: type: object properties: nextCursor: anyOf: - type: string minLength: 16 maxLength: 2048 pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$ - type: 'null' hasMore: type: boolean required: - nextCursor - hasMore additionalProperties: false total: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' totalApproximate: type: - boolean - 'null' account: anyOf: - type: object properties: object: type: string const: account id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ platform: type: string enum: - youtube - tiktok - instagram - meta_ad_library handle: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' name: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' url: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' required: - object - id - platform - handle - name - url additionalProperties: false - type: 'null' observedAt: type: string pattern: >- ^\d{4}-(0[1-9]|1[0-2])-([0-2]\d|3[01])T([01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d{1,9})?(?:Z|[+-](?:[01]\d|2[0-3]):[0-5]\d)$ cached: type: boolean usage: type: object properties: creditsCharged: type: integer minimum: 0 maximum: 9007199254740991 lines: maxItems: 8 type: array items: type: object properties: part: type: string enum: - fetch credits: type: integer minimum: 1 maximum: 9007199254740991 required: - part - credits additionalProperties: false required: - creditsCharged - lines additionalProperties: false required: - object - data - page - total - totalApproximate - account - observedAt - cached - usage additionalProperties: false ErrorEnvelope: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: error: type: object properties: code: type: string enum: - invalid_input - unauthenticated - invalid_credential - credential_conflict - forbidden - policy_blocked - route_disabled - route_degraded - not_found - bootstrap_conflict - last_owner_conflict - revision_conflict - idempotency_conflict - unavailable_private - unavailable_restricted - unavailable_removed - unsupported_object - unsupported_media - insufficient_credits - limit_exceeded - rate_limited - source_changed - network_timeout - network_transport - media_invalid - storage_unavailable - retry_exhausted - internal_error message: type: string minLength: 1 maxLength: 240 retryable: type: boolean requestId: type: string minLength: 8 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$ details: type: object propertyNames: type: string additionalProperties: type: - string - number - boolean required: - code - message - retryable - requestId - details additionalProperties: false required: - error additionalProperties: false securitySchemes: bearerApiKey: type: http scheme: bearer ````