> ## 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. # Look up one public item > Costs 1 credit for a live fetch, and for the first time a workspace is served a stored observation. A repeat within maxAge is free and reports cached true while the store serves the observation the workspace already paid for; once another workspace or an import records changed counts, the next repeat costs 1 credit. Every error charges nothing: the answer is always an item or a typed failure, never a job to poll. Responses carry Refmatter-Credits-Charged, and a success also carries Server-Timing. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/items/lookup 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/items/lookup: get: tags: - items summary: Look up one public item description: >- Costs 1 credit for a live fetch, and for the first time a workspace is served a stored observation. A repeat within maxAge is free and reports cached true while the store serves the observation the workspace already paid for; once another workspace or an import records changed counts, the next repeat costs 1 credit. Every error charges nothing: the answer is always an item or a typed failure, never a job to poll. Responses carry Refmatter-Credits-Charged, and a success also carries Server-Timing. operationId: itemsLookup parameters: - name: url in: query required: true description: Absolute http or https URL of one post, video, short or ad schema: type: string minLength: 1 maxLength: 2048 - name: include in: query required: false description: Also return a transcript built from captions schema: type: string enum: - transcript - name: maxAge in: query required: false description: >- How fresh a stored observation must be to be served: 0 or a whole number of minutes, hours or days up to 365d, such as 30m, 1h or 7d. Default 1h; 0 always fetches live schema: type: string pattern: ^(0|[1-9][0-9]{0,5}[mhd])$ default: 1h responses: '200': description: The item as it was observed headers: Refmatter-Credits-Charged: description: Credits this response charged the workspace schema: type: integer minimum: 0 Refmatter-Credits-Remaining: description: Credits the workspace has left after this response schema: type: integer Server-Timing: description: 'Durations of the phases that ran: fetch, persist, total' 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/Item' '400': description: Invalid request headers: Refmatter-Credits-Charged: description: >- Credits this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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 this response charged the workspace: 0, as 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: Item: $schema: https://json-schema.org/draft/2020-12/schema type: object properties: object: type: string const: item 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' 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 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 transcript: anyOf: - type: object properties: language: type: string minLength: 2 maxLength: 16 source: type: string enum: - captions - automatic_captions segments: maxItems: 20000 type: array items: type: object properties: startMs: type: integer minimum: 0 maximum: 9007199254740991 endMs: type: integer minimum: 0 maximum: 9007199254740991 text: type: string minLength: 1 maxLength: 4000 required: - startMs - endMs - text additionalProperties: false text: type: string maxLength: 2000000 required: - language - source - segments - text additionalProperties: false - type: 'null' unavailableFields: maxItems: 12 type: array items: type: string enum: - author - title - text - publishedAt - durationMs - stats.views - stats.likes - stats.comments - stats.shares - stats.saves - thumbnails - transcript ad: anyOf: - type: object properties: archiveId: type: string pattern: ^[0-9]{6,25}$ deeplinkId: anyOf: - type: string pattern: ^[0-9]{6,25}$ - type: 'null' pageId: type: string pattern: ^[0-9]{1,32}$ pageName: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' byline: 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' platforms: maxItems: 16 type: array items: type: string minLength: 1 maxLength: 64 displayFormat: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' collationId: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' collationCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' 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' creatives: maxItems: 30 type: array items: type: object properties: index: type: integer minimum: 0 maximum: 9007199254740991 kind: type: string enum: - image - video title: anyOf: - type: string minLength: 0 maxLength: 1000 - type: 'null' body: anyOf: - type: string minLength: 0 maxLength: 10000 - type: 'null' caption: anyOf: - type: string minLength: 0 maxLength: 1000 - type: 'null' linkUrl: anyOf: - type: string minLength: 1 maxLength: 2048 - type: 'null' linkDescription: anyOf: - type: string minLength: 0 maxLength: 1000 - type: 'null' callToAction: anyOf: - type: string minLength: 0 maxLength: 160 - type: 'null' callToActionType: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' thumbnail: anyOf: - 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 - type: 'null' required: - index - kind - title - body - caption - linkUrl - linkDescription - callToAction - callToActionType - thumbnail additionalProperties: false required: - archiveId - deeplinkId - pageId - pageName - byline - active - startedAt - endedAt - platforms - displayFormat - collationId - collationCount - spend - impressions - reach - currency - creatives additionalProperties: false - type: 'null' tiktok: anyOf: - type: object properties: authorSecUid: anyOf: - type: string minLength: 1 maxLength: 256 - type: 'null' authorVerified: type: - boolean - 'null' reposts: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' hashtags: maxItems: 256 type: array items: type: string minLength: 1 maxLength: 256 music: anyOf: - type: object properties: id: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' title: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' authorName: anyOf: - type: string minLength: 0 maxLength: 500 - type: 'null' original: type: - boolean - 'null' required: - id - title - authorName - original additionalProperties: false - type: 'null' isAd: type: - boolean - 'null' aiGenerated: type: - boolean - 'null' width: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' originalLanguage: anyOf: - type: string minLength: 1 maxLength: 35 - type: 'null' captionLanguages: maxItems: 64 type: array items: type: string minLength: 1 maxLength: 35 required: - authorSecUid - authorVerified - reposts - hashtags - music - isAd - aiGenerated - width - height - originalLanguage - captionLanguages additionalProperties: false - type: 'null' instagram: anyOf: - type: object properties: mediaId: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' productType: anyOf: - type: string minLength: 1 maxLength: 64 - type: 'null' carouselCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' likesHidden: type: - boolean - 'null' hasAudio: type: - boolean - 'null' captionEdited: type: - boolean - 'null' authorVerified: type: - boolean - 'null' width: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' height: anyOf: - type: integer exclusiveMinimum: 0 maximum: 9007199254740991 - type: 'null' accessibilityCaption: anyOf: - type: string minLength: 0 maxLength: 2000 - type: 'null' required: - mediaId - productType - carouselCount - likesHidden - hasAudio - captionEdited - authorVerified - width - height - accessibilityCaption additionalProperties: false - type: 'null' youtube: anyOf: - type: object properties: availability: anyOf: - type: string enum: - public - private - members_only - purchased - login_required - removed - unavailable - type: 'null' liveState: anyOf: - type: string enum: - not_live - live - post_live - premiere_upcoming - type: 'null' captionTracks: maxItems: 64 type: array items: type: object properties: language: type: string minLength: 1 maxLength: 35 kind: type: string enum: - manual - automatic required: - language - kind additionalProperties: false categories: anyOf: - maxItems: 32 type: array items: type: string minLength: 1 maxLength: 160 - type: 'null' tags: anyOf: - maxItems: 500 type: array items: type: string minLength: 1 maxLength: 500 - type: 'null' channelFollowerCount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' commentCountApproximate: type: - boolean - 'null' required: - availability - liveState - captionTracks - categories - tags - channelFollowerCount - commentCountApproximate 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 - id - platform - kind - url - author - title - text - publishedAt - durationMs - stats - thumbnails - transcript - unavailableFields - ad - tiktok - instagram - youtube - 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 ````