> **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):** <https://www.socialfetch.dev/docs/api/v1/saved-queries/post>
- **Markdown (.mdx) URL:** <https://www.socialfetch.dev/docs/api/v1/saved-queries/post.mdx>

## 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:** <https://www.socialfetch.dev/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`).

---
# Create a saved query (https://www.socialfetch.dev/docs/api/v1/saved-queries/post)

## Summary

Create a Boolean query that runs on a schedule and stores the posts it matches.

**Tags:** `Saved queries`

## HTTP

- **Method:** POST
- **Path:** `/v1/saved-queries`
- **Base URL:** `https://api.socialfetch.dev`

## Capability summary

- **SDK mapping:** HTTP only today
- **Pagination:** none

## 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_...`)

## Request body

- **Required:** no; content type `application/json`

**Shape:**

- **name** (required) — type `string`; minLength: 1; maxLength: 120. A name for the query, shown in the dashboard and in alerts.
- **query** (required) — type `string`; minLength: 1; maxLength: 8192. The Boolean query. Check it for free first with POST /v1/query/validate.
- **syntax** (optional) — type `string`; enum: native, x, onclusive, talkwalker, brandwatch, meltwater. Syntax the query is written in: `native` (Social Fetch's Boolean language), or another tool's to import: `x` (X search), `onclusive`, `talkwalker`, `brandwatch` (also Cision Social Listening) or `meltwater`.
- **platforms** (optional) — type `array`. Platforms to search. Empty means every platform search covers.
  - _items:_
    - type `string`; enum: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews
- **maxCreditsPerRun** (required) — type `integer`; minimum: 1; maximum: 10000. The most one run may charge, held while it runs as with POST /v1/query/search; what isn't used is given back.
- **cadenceMinutes** (required) — type `integer`; minimum: 15; maximum: 10080. Minutes between scheduled runs, from 15 to 10080 (a week).
- **monthlyCreditCap** (optional) — type `integer`; minimum: 1; nullable. The most all its runs may charge in a calendar month (UTC). Null for no cap beyond each run's.
- **webhookEndpointId** (optional) — type `string`; minLength: 1; nullable. A webhook endpoint of this workspace to send new matches to (event `saved_query.matches`), spikes (event `saved_query.spike`: far more posts in 24 hours than its usual day), volume alerts (event `saved_query.threshold`) and briefings (event `saved_query.briefing`).
- **alertThreshold** (optional) — type `object`; nullable. A volume alert: when a run brings the posts it found in the trailing `window` to at least `posts`, it sends the `saved_query.threshold` webhook event, at most once a window. The first run of a query or of a new wording doesn't alert (it finds the backlog). Null for none.
  - **posts** (required) — type `integer`; minimum: 1; maximum: 1000000. Alert when it has found at least this many posts in the window.
  - **window** (required) — type `string`; enum: hour, day. The trailing hour or day the posts are counted over, by when they were found. The query must run at least that often: an `hour` window needs `cadenceMinutes` of 60 or less, a `day` window 1440 or less.
- **briefing** (optional) — type `string`; enum: daily, weekly, null; nullable. A briefing on what it found: `daily` covers the day before (UTC) and comes at 08:00 UTC; `weekly` covers Monday to Sunday and comes on Monday at 08:00 UTC. It counts the posts, the change on the period before, the stories, each platform's posts, the loudest voices and the 5 most engaged posts, is shown on the query in the Listening app, and is sent to its webhook endpoint as the `saved_query.briefing` event. Only for an active query that ran in the period without failing. Null for none, the default.
- **noise** (optional) — type `array`. Kinds of post its runs leave out: `jobs` (job ads and job seekers' posts), `giveaways` (giveaway and contest entry posts), `crypto-spam` (crypto promotion and money scams). Checked on each post after it's found, so a run costs the same. Empty, the default, leaves everything in.
  - _items:_
    - type `string`; enum: jobs, giveaways, crypto-spam
- **sentiment** (optional) — type `boolean`. Give each new match a sentiment estimate (positive, neutral or negative), for 1 credit per 10 matches given one, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. Only matches given one are charged. A match keeps its sentiment: it's never estimated or charged again. Default false.
- **insights** (optional) — type `object`; nullable. Judge each new match: is it about what the query is about, what is it (a complaint, question, praise, buying, promotion or news), does it need a reply, is it a risk, and up to 3 yes/no questions of your own. 1 credit per 10 matches given them, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. A match keeps its insights: it's never judged or charged again. Matches not about it are still kept and returned; filter with `relevance`. With insights, alerts and spikes count only matches that aren't `unrelated`. Not available for zero-retention workspaces. Null or absent for off.
  - **about** (required) — type `string`; minLength: 2; maxLength: 200. What the topic is about, in a few words: the name and what it is, so posts using the word another way can be told apart. For example "Notion, the note-taking app" or "Jaguar, the car brand".
  - **questions** (optional) — type `array`. Up to 3 yes/no questions of your own, asked of every post, such as "Does the post mention sizing or fit?". Each post's answers come back in `insights.answers`, in this order.
    - _items:_
      - type `string`; minLength: 5; maxLength: 200
- **platformSearches** (optional) — type `object`; nullable. Searches each run makes on a platform instead of those planned from the query, by platform (`platformSearches` on `POST /v1/query/search`). Null for none: every platform searched as planned.
  - **twitter** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **reddit** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **youtube** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **tiktok** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **linkedin** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **instagram** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **threads** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
  - **hackernews** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
    - _items:_
      - type `string`; minLength: 1; maxLength: 200
- **runNow** (optional) — type `boolean`. Run it once straight away rather than at its first scheduled time. Default true.

**Example:**

```json
{
  "name": "string",
  "query": "string",
  "maxCreditsPerRun": 0,
  "cadenceMinutes": 0
}
```

## Responses (status codes)

- **201**: The newly created saved query.
- **400**: The query can't be read, the webhook endpoint isn't this workspace's, the workspace has reached its saved-queries limit, or it keeps no request content.
- **401**: Missing or invalid API key
- **403**: The caller's role in this workspace can't manage its saved queries.
- **500**: Unexpected error

## Response body (201)

The newly created saved query.

### Field outline

- **data** (required) — type `object`. Endpoint-specific response payload.
  - **id** (required) — type `string`
  - **name** (required) — type `string`
  - **query** (required) — type `string`. The current version's query, as written.
  - **syntax** (required) — type `string`; enum: native, x, onclusive, talkwalker, brandwatch, meltwater. Syntax the query is written in: `native` (Social Fetch's Boolean language), or another tool's to import: `x` (X search), `onclusive`, `talkwalker`, `brandwatch` (also Cision Social Listening) or `meltwater`.
  - **normalizedQuery** (required) — type `string`. The current version, in Social Fetch syntax.
  - **versionId** (required) — type `string`. The current version's id.
  - **platforms** (required) — type `array`
    - _items:_
      - type `string`; enum: twitter, reddit, youtube, tiktok, linkedin, instagram, threads, hackernews
  - **maxCreditsPerRun** (required) — type `integer`
  - **cadenceMinutes** (required) — type `integer`
  - **monthlyCreditCap** (required) — type `integer`; nullable
  - **spentThisMonth** (required) — type `integer`. Credits its runs charged this calendar month (UTC).
  - **status** (required) — type `string`; enum: active, paused, capped, broken. `active` runs on its schedule; `paused` doesn't; `capped` has spent its monthly credit cap and runs again next month, or when the cap is raised; `broken` stopped after its runs kept failing (see `statusReason`).
  - **statusReason** (required) — type `string`; nullable
  - **nextRunAt** (required) — type `string`; nullable. When it runs next, ISO 8601; null while it isn't active.
  - **lastRunAt** (required) — type `string`; nullable
  - **webhookEndpointId** (required) — type `string`; nullable
  - **alertThreshold** (required) — type `object`; nullable. A volume alert: when a run brings the posts it found in the trailing `window` to at least `posts`, it sends the `saved_query.threshold` webhook event, at most once a window. The first run of a query or of a new wording doesn't alert (it finds the backlog). Null for none.
    - **posts** (required) — type `integer`; minimum: 1; maximum: 1000000. Alert when it has found at least this many posts in the window.
    - **window** (required) — type `string`; enum: hour, day. The trailing hour or day the posts are counted over, by when they were found. The query must run at least that often: an `hour` window needs `cadenceMinutes` of 60 or less, a `day` window 1440 or less.
  - **briefing** (required) — type `string`; enum: daily, weekly, null; nullable. A briefing on what it found: `daily` covers the day before (UTC) and comes at 08:00 UTC; `weekly` covers Monday to Sunday and comes on Monday at 08:00 UTC. It counts the posts, the change on the period before, the stories, each platform's posts, the loudest voices and the 5 most engaged posts, is shown on the query in the Listening app, and is sent to its webhook endpoint as the `saved_query.briefing` event. Only for an active query that ran in the period without failing. Null for none, the default.
  - **noise** (required) — type `array`. Kinds of post its runs leave out: `jobs` (job ads and job seekers' posts), `giveaways` (giveaway and contest entry posts), `crypto-spam` (crypto promotion and money scams). Checked on each post after it's found, so a run costs the same. Empty, the default, leaves everything in.
    - _items:_
      - type `string`; enum: jobs, giveaways, crypto-spam
  - **sentiment** (required) — type `boolean`. Give each new match a sentiment estimate (positive, neutral or negative), for 1 credit per 10 matches given one, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. Only matches given one are charged. A match keeps its sentiment: it's never estimated or charged again. Default false.
  - **insights** (required) — type `object`; nullable. Judge each new match: is it about what the query is about, what is it (a complaint, question, praise, buying, promotion or news), does it need a reply, is it a risk, and up to 3 yes/no questions of your own. 1 credit per 10 matches given them, on top of each run's maxCreditsPerRun but within monthlyCreditCap when one is set. A match keeps its insights: it's never judged or charged again. Matches not about it are still kept and returned; filter with `relevance`. With insights, alerts and spikes count only matches that aren't `unrelated`. Not available for zero-retention workspaces. Null or absent for off.
    - **about** (required) — type `string`; minLength: 2; maxLength: 200. What the topic is about, in a few words: the name and what it is, so posts using the word another way can be told apart. For example "Notion, the note-taking app" or "Jaguar, the car brand".
    - **questions** (optional) — type `array`. Up to 3 yes/no questions of your own, asked of every post, such as "Does the post mention sizing or fit?". Each post's answers come back in `insights.answers`, in this order.
      - _items:_
        - type `string`; minLength: 5; maxLength: 200
  - **platformSearches** (required) — type `object`; nullable. Searches each run makes on a platform instead of those planned from the query, by platform (`platformSearches` on `POST /v1/query/search`). Null for none: every platform searched as planned.
    - **twitter** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **reddit** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **youtube** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **tiktok** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **linkedin** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **instagram** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **threads** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
    - **hackernews** (optional) — type `array`. Searches to run on this platform instead of those planned from the query, in its own syntax (Instagram: hashtags, with or without `#`). Posts found are still checked against the whole query.
      - _items:_
        - type `string`; minLength: 1; maxLength: 200
  - **matchCount** (required) — type `integer`. Matches stored for it.
  - **createdAt** (required) — type `string`
  - **updatedAt** (required) — type `string`
- **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": {
    "id": "string",
    "name": "string",
    "query": "string",
    "syntax": "native",
    "normalizedQuery": "string",
    "versionId": "string",
    "platforms": [
      "twitter"
    ],
    "maxCreditsPerRun": 0,
    "cadenceMinutes": 0,
    "monthlyCreditCap": 0,
    "spentThisMonth": 0,
    "status": "active",
    "statusReason": "string",
    "nextRunAt": "string",
    "lastRunAt": "string",
    "webhookEndpointId": "string",
    "alertThreshold": {
      "posts": 0,
      "window": "hour"
    },
    "briefing": "daily",
    "noise": [
      "jobs"
    ],
    "sentiment": false,
    "insights": {
      "about": "string",
      "questions": [
        "string"
      ]
    },
    "platformSearches": {
      "twitter": [
        "string"
      ],
      "reddit": [
        "string"
      ],
      "youtube": [
        "string"
      ],
      "tiktok": [
        "string"
      ],
      "linkedin": [
        "string"
      ],
      "instagram": [
        "string"
      ],
      "threads": [
        "string"
      ],
      "hackernews": [
        "string"
      ]
    },
    "matchCount": 0,
    "createdAt": "string",
    "updatedAt": "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**: The query can't be read, the webhook endpoint isn't this workspace's, the workspace has reached its saved-queries limit, or it keeps no request content. **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.
- **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.