> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration. ## This page - **On-site (HTML):** - **Markdown (.mdx) URL:** ## API base URL and authentication - **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev` - **Authentication:** send `x-api-key: sfk_...` on `/v1/**` and `/v2/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route). - **OpenAPI JSON:** ## Recommended docs entrypoints (this site) - [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown). - [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope. - [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`. - [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — every operation with identifiers, pagination, outcomes, media download, credits, and its SDK method. Generated from OpenAPI, so use it for route selection instead of scanning individual pages. - [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples. - [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, Make custom app, SDK, and REST API connection paths. - [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install. - [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 910 endpoint tools, plus docs_search/docs_read for implementation help. - [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples. - [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start. - [Make integration](https://www.socialfetch.dev/docs/integrations/make.mdx) — custom app modules for Make scenarios, API key credentials, and module catalog. - [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI). - [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls). - [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist. - [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping. - [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages. - [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance. - [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs. - Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract. ## Markdown docs convention - Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`). - Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`). - Published blog posts use the same convention: `/blog/{slug}` → `/blog/{slug}.mdx`, or `Accept: text/markdown` on the HTML URL (`Vary: Accept`). --- # List a saved query's matches (https://www.socialfetch.dev/docs/api/v1/saved-queries/id/matches/get) ## Summary List the posts a saved query matched, newest first. **Tags:** `Saved queries` ## HTTP - **Method:** GET - **Path:** `/v1/saved-queries/{id}/matches` - **Base URL:** `https://api.socialfetch.dev` ## Capability summary - **SDK mapping:** HTTP only today - **Accepted identifiers:** `id` (path), `author` (query) - **Pagination:** cursor via `cursor`, next cursor: `data.page.nextCursor`, has more: `data.page.hasMore` ## Credits - **Base:** 0 credits per successful lookup. - **Maximum on success (200):** 0 credits. - **Failed requests (`lookup_failed`, `503`):** not charged. - **Authoritative field:** `meta.creditsCharged`. ## Authentication - **`x-api-key`**: API key (`sfk_...`) ## Parameters ### `id` (path) - **Required:** yes - **Constraints:** type `string`; minLength: 1 - **Description:** The saved query's id. ### `since` (query) - **Required:** no - **Constraints:** type `string` - **Description:** Only matches first seen at or after this time. ### `until` (query) - **Required:** no - **Constraints:** type `string` - **Description:** Only matches first seen before this time. ### `platform` (query) - **Required:** no - **Constraints:** type `string`; enum: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews - **Description:** A platform a search runs on: `twitter` (X), `reddit`, `youtube`, `tiktok`, `linkedin`, `instagram` (searched by hashtag, so only posts that use the hashtag are found), `threads` (searched by plain words, one short page a search, so it can miss posts) or `hackernews` (stories and comments). More platforms follow. ### `sentiment` (query) - **Required:** no - **Constraints:** type `string`; enum: positive, neutral, negative - **Description:** Only matches with this sentiment (a person's, where one was set, else the estimate). ### `relevance` (query) - **Required:** no - **Constraints:** type `string`; enum: relevant, about, passing, unrelated - **Description:** Only matches with this relevance (a person's, where one was set, else the estimate); `relevant` is anything but `unrelated`. Matches without insights count as relevant. ### `attention` (query) - **Required:** no - **Constraints:** type `string`; enum: needs_reply, risk - **Description:** Only matches insights flagged as needing a reply, or as a risk. ### `kind` (query) - **Required:** no - **Constraints:** type `string`; enum: complaint, question, praise, buying, promotion, news - **Description:** Only matches insights judged to be this kind of post. ### `author` (query) - **Required:** no - **Constraints:** type `string`; minLength: 1; maxLength: 200 - **Description:** Only posts by this author: their handle as the post gives it (`author.handle`), without the `@`. Pair with `platform` when the same handle could be on several. ### `q` (query) - **Required:** no - **Constraints:** type `string`; minLength: 1; maxLength: 200 - **Description:** Only posts whose title or text contains this, ignoring case. ### `sort` (query) - **Required:** no - **Constraints:** type `string`; enum: posted, found - **Description:** `posted` (default): the newest posts first, by when they were posted (or found, when the platform gave no time). `found`: the most recently found first, for keeping a copy in step. ### `limit` (query) - **Required:** no - **Constraints:** type `integer`; minimum: 1; maximum: 100 - **Description:** Matches a page, up to 100. Default 50. ### `cursor` (query) - **Required:** no - **Constraints:** type `string`; minLength: 1 - **Description:** The `nextCursor` of the previous page, with the same `sort`. ## Pagination This endpoint uses **cursor-based pagination** via the `cursor` query parameter. - Read **hasMore** from `data.page.hasMore`. - When that value is `true`, read **nextCursor** from `data.page.nextCursor` and pass it as the `cursor` query parameter on the **next** request (URL-encode when building a query string). - Omit `cursor` on the **first** request. - Stop when **hasMore** is `false` or **nextCursor** is null (end of list). ## Responses (status codes) - **200**: The saved query's matches, newest first. - **400**: Invalid cursor, limit, time window or platform. - **401**: Missing or invalid API key - **403**: The caller's role in this workspace can't manage its saved queries. - **404**: Saved query not found, or not owned by this workspace. - **500**: Unexpected error ## Response body (200) The saved query's matches, newest first. ### Field outline - **data** (required) — type `object`. Endpoint-specific response payload. - **matches** (required) — type `array`. The saved query's matches, newest first. - _items:_ - **mention** (required) — type `object`. A post the query matched. - **versionId** (required) — type `string`. The version of the query that first found it. - **runId** (required) — type `string`. The run that first found it. - **firstSeenAt** (required) — type `string` - **lastSeenAt** (required) — type `string` - **page** (required) — type `object`. Pagination state: pass `page.nextCursor` as `cursor` for the next page. - **hasMore** (required) — type `boolean`. Whether another page is available. - **nextCursor** (required) — type `string`; nullable. Cursor to pass in the next request when more pages exist; null on the last page. - **meta** (required) — type `object`. Metadata describing the request and billing outcome. - **requestId** (required) — type `string`; minLength: 1. Unique request identifier for tracing this API call. - **creditsCharged** (required) — type `integer`; minimum: 0. Credits charged for this request. - **version** (required) — type `string`; enum: v1. Public API version that served the response. ### Example JSON (derived from schema) ```json { "data": { "matches": [ { "mention": { "key": "string", "platform": "twitter", "id": "string", "url": "string", "title": "string", "texts": [ { "field": null, "text": null } ], "text": "string", "evaluatedFields": [ "string" ], "createdAt": "string", "createdAtIsEstimate": false, "author": { "id": "string", "handle": "string", "name": "string", "followers": 0, "verified": false }, "community": { "id": "string", "name": "string" }, "language": "string", "languageIsDetected": false, "country": "string", "types": [ "string" ], "thread": { "parentId": "string", "conversationId": "string", "quotedId": "string", "repostedId": "string" }, "metrics": { "likes": 0, "views": 0, "comments": 0, "shares": 0 }, "reach": { "estimate": 0, "basis": "views" }, "hashtags": [ "string" ], "mentions": [ "string" ], "links": [ "string" ], "matchedFrom": [ "string" ], "outcome": "match", "matchedTerms": [ "string" ], "unevaluableFields": [ "string" ], "categories": [ "string" ], "uncertainCategories": [ "string" ], "duplicateOf": { "key": "string", "reason": "repost" } }, "versionId": "string", "runId": "string", "firstSeenAt": "string", "lastSeenAt": "string" } ], "page": { "hasMore": false, "nextCursor": "string" } }, "meta": { "requestId": "string", "creditsCharged": 0, "version": "v1" } } ``` ### Machine-readable error codes When an error JSON body is returned, it may include one of these `error.code` values (derived from the OpenAPI schemas for this operation; additional codes may exist at runtime): - `bad_request` ## Error handling & retries Interpret HTTP status codes using the descriptions below. Do not assume a JSON body unless the OpenAPI schema defines one for that status. - **400**: Invalid cursor, limit, time window or platform. **Retry:** Fix the request; retrying the same invalid payload will not help. - **401**: Missing or invalid API key **Retry:** Fix the API key first; retrying without changes will not help. - **403**: The caller's role in this workspace can't manage its saved queries. - **404**: Saved query not found, or not owned by this workspace. - **500**: Unexpected error ### Suggested client defaults - Send the API key using the `x-api-key` header on every request. - On `503` (and sometimes `502`), retry with backoff; cap retries and surface a clear error to the user. - On `402`, surface an actionable billing message rather than blind retries.