> ## 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. # List comments > 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. YouTube videos only today; an item of another platform answers 422 with a hint. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/comments 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/comments: get: tags: - comments summary: List comments 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. YouTube videos only today; an item of another platform answers 422 with a hint. operationId: commentsList parameters: - name: item in: query required: false description: >- Item selector: a natural key such as youtube:dQw4w9WgXcQ, or the item URL schema: type: string minLength: 1 maxLength: 2048 - name: sort in: query required: false description: Comment ordering schema: enum: - top - newest default: top - 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 item comments 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: $ref: '#/components/schemas/CommentList' '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: CommentList: $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: comment id: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ itemId: type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ parentId: anyOf: - type: string pattern: >- ^(youtube|tiktok|instagram|meta_ad_library):[A-Za-z0-9._-]{1,128}$ - type: 'null' 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' authorIsCreator: type: - boolean - 'null' text: type: string minLength: 0 maxLength: 10000 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' stats: type: object properties: likes: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' replies: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' required: - likes - replies additionalProperties: false likesApproximate: type: - boolean - 'null' pinned: type: - boolean - 'null' required: - object - id - itemId - parentId - author - authorIsCreator - text - publishedAt - publishedText - stats - likesApproximate - pinned 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 ````