> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xquik.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create extraction

> Run an extraction job using one of 23 available tools

<blockquote className="agent-llms-directive">
  For the complete documentation index, see <a href="/llms.txt">llms.txt</a>.
</blockquote>

<Callout icon="coins" color="#5c3327">
  **1 credit per result extracted** · [All plans](https://xquik.com/#pricing) from \$0.00012/credit
</Callout>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://xquik.com/api/v1/extractions \
    -H "x-api-key: xq_YOUR_KEY_HERE" \
    -H "Content-Type: application/json" \
    -d '{
      "toolType": "reply_extractor",
      "targetTweetId": "1893704267862470862",
      "resultsLimit": 500
    }' | jq
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://xquik.com/api/v1/extractions", {
    method: "POST",
    headers: {
      "x-api-key": "xq_YOUR_KEY_HERE",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      toolType: "reply_extractor",
      targetTweetId: "1893704267862470862",
      resultsLimit: 500,
    }),
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://xquik.com/api/v1/extractions",
      headers={"x-api-key": "xq_YOUR_KEY_HERE"},
      json={
          "toolType": "reply_extractor",
          "targetTweetId": "1893704267862470862",
          "resultsLimit": 500,
      },
  )
  data = response.json()
  ```

  ```go Go theme={null}
  package main

  import (
      "bytes"
      "encoding/json"
      "fmt"
      "net/http"
  )

  func main() {
      body, _ := json.Marshal(map[string]interface{}{
          "toolType":      "reply_extractor",
          "targetTweetId": "1893704267862470862",
          "resultsLimit":  500,
      })

      req, err := http.NewRequest("POST", "https://xquik.com/api/v1/extractions", bytes.NewReader(body))
      if err != nil {
          panic(err)
      }
      req.Header.Set("x-api-key", "xq_YOUR_KEY_HERE")
      req.Header.Set("Content-Type", "application/json")

      resp, err := http.DefaultClient.Do(req)
      if err != nil {
          panic(err)
      }
      defer resp.Body.Close()

      var data map[string]interface{}
      if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
          panic(err)
      }
      fmt.Println(data)
  }
  ```
</CodeGroup>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your API key. Session cookie authentication is also supported.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

## Body

<ParamField body="toolType" type="string" required>
  Extraction tool to run. See [tool types](#tool-types) below.
</ParamField>

<ParamField body="targetTweetId" type="string">
  Tweet ID to extract from. Required for `reply_extractor`, `repost_extractor`, `quote_extractor`, `thread_extractor`, `article_extractor`.
</ParamField>

<ParamField body="targetUsername" type="string">
  X username to extract from. The `@` prefix is automatically stripped if included. Required for `follower_explorer`, `following_explorer`, `verified_follower_explorer`, `mention_extractor`, `post_extractor`, `user_likes`, and `user_media`.
</ParamField>

<ParamField body="targetCommunityId" type="string">
  Community ID to extract from. Required for `community_extractor`, `community_moderator_explorer`, `community_post_extractor`.
</ParamField>

<ParamField body="searchQuery" type="string">
  Search query string. Required for `people_search`, `community_search`, `tweet_search_extractor`.
</ParamField>

<ParamField body="targetListId" type="string">
  X List ID to extract from. Required for `list_member_extractor`, `list_post_extractor`, `list_follower_explorer`.
</ParamField>

<ParamField body="targetSpaceId" type="string">
  X Space ID to extract from. Required for `space_explorer`.
</ParamField>

<ParamField body="resultsLimit" type="integer">
  Maximum number of results to extract. When set, extraction stops after reaching this limit instead of fetching all available data. Useful for controlling costs and extracting a specific sample size. Omit to extract all available results.
</ParamField>

<ParamField body="queryType" type="string">
  Search sort for `tweet_search_extractor` and `community_search`. Values: `Latest`, `Top`. Defaults to `Latest` for tweet search exports and `Top` for community search jobs.
</ParamField>

<ParamField body="includeReplies" type="boolean">
  Include reply tweets for `post_extractor`. Omit or set to `false` to extract profile posts without replies.
</ParamField>

## Tweet search filters

The following parameters apply only to `tweet_search_extractor`. They are converted to X search operators internally and combined with `searchQuery`.

<ParamField body="fromUser" type="string">
  Filter tweets by author username. Do not include the `@` prefix.
</ParamField>

<ParamField body="toUser" type="string">
  Filter tweets directed to a specific user.
</ParamField>

<ParamField body="mentioning" type="string">
  Filter tweets mentioning a specific user.
</ParamField>

<ParamField body="language" type="string">
  Language code filter (e.g. `en`, `tr`, `es`, `ja`).
</ParamField>

<ParamField body="sinceDate" type="string">
  Start date in `YYYY-MM-DD` format. Only tweets on or after this date are returned.
</ParamField>

<ParamField body="untilDate" type="string">
  End date in `YYYY-MM-DD` format. Only tweets before this date are returned.
</ParamField>

<ParamField body="mediaType" type="string">
  Filter by attached media type. Values: `images`, `videos`, `gifs`, `media` (any media).
</ParamField>

<ParamField body="minFaves" type="integer">
  Minimum number of likes a tweet must have.
</ParamField>

<ParamField body="minRetweets" type="integer">
  Minimum number of retweets a tweet must have.
</ParamField>

<ParamField body="minReplies" type="integer">
  Minimum number of replies a tweet must have.
</ParamField>

<ParamField body="verifiedOnly" type="boolean">
  When `true`, only return tweets from verified accounts.
</ParamField>

<ParamField body="replies" type="string">
  Control reply inclusion. Values: `include` (default), `exclude`, `only`.
</ParamField>

<ParamField body="retweets" type="string">
  Control retweet inclusion. Values: `include` (default), `exclude`, `only`.
</ParamField>

<ParamField body="exactPhrase" type="string">
  Exact phrase match. The value is wrapped in quotes and added to the search query (e.g. `"breaking news"`).
</ParamField>

<ParamField body="excludeWords" type="string">
  Comma-separated words to exclude from results. Each word is prefixed with `-` in the search query.
</ParamField>

<ParamField body="advancedQuery" type="string">
  Raw X search operator syntax appended to the query. Use this for operators not covered by the other filter fields (e.g. `filter:links`, `url:example.com`).
</ParamField>

<Note>
  These filters are ignored for all other tool types. They are converted to X search operators and combined with `searchQuery` before execution.
</Note>

## Tool types

Each extraction job needs one target field based on `toolType`. `resultsLimit`
works with every type when you want to cap returned rows.

<CardGroup cols={2}>
  <Card title="Tweet target" icon="message-circle">
    Use `targetTweetId` for tweet-centered jobs:

    * `article_extractor` extracts article content from a tweet.
    * `favoriters` extracts users who liked a tweet.
    * `quote_extractor` extracts users who quote-tweeted a tweet.
    * `reply_extractor` extracts users who replied to a tweet.
    * `repost_extractor` extracts users who retweeted a tweet.
    * `thread_extractor` extracts all tweets in a thread.
  </Card>

  <Card title="Username target" icon="user">
    Use `targetUsername` for account-centered jobs:

    * `follower_explorer` extracts followers of an account.
    * `following_explorer` extracts accounts followed by a user.
    * `mention_extractor` extracts tweets mentioning an account.
    * `post_extractor` extracts posts from an account.
    * `user_likes` extracts tweets liked by a user.
    * `user_media` extracts media posts from a user.
    * `verified_follower_explorer` extracts verified followers of an account.
  </Card>

  <Card title="Community target" icon="users">
    Use `targetCommunityId` for community jobs:

    * `community_extractor` extracts members of a community.
    * `community_moderator_explorer` extracts moderators of a community.
    * `community_post_extractor` extracts posts from a community.
  </Card>

  <Card title="Search query" icon="search">
    Use `searchQuery` for keyword jobs:

    * `community_search` searches posts within a community.
    * `people_search` searches for users by keyword.
    * `tweet_search_extractor` searches and extracts tweets by keyword or hashtag.
  </Card>

  <Card title="List target" icon="list">
    Use `targetListId` for X List jobs:

    * `list_follower_explorer` extracts followers of a list.
    * `list_member_extractor` extracts members of a list.
    * `list_post_extractor` extracts posts from a list.
  </Card>

  <Card title="Space target" icon="radio">
    Use `targetSpaceId` for Space jobs:

    * `space_explorer` extracts participants of a Space.

    Store `targetSpaceId` beside the returned extraction `id`. Poll
    [Get Extraction](/api-reference/extractions/get) or use
    [Export Extraction](/api-reference/extractions/export) after completion to
    read participant user rows.
  </Card>
</CardGroup>

## Response

<Tabs>
  <Tab title="202 Accepted">
    <ResponseField name="id" type="string">Unique extraction job ID (UUID).</ResponseField>
    <ResponseField name="toolType" type="string">Tool type used for this extraction.</ResponseField>
    <ResponseField name="status" type="string">Job status. `running` when first created.</ResponseField>

    ```json theme={null}
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "toolType": "reply_extractor",
      "status": "running"
    }
    ```

    <Info>
      Extraction runs asynchronously. Poll [Get Extraction](/api-reference/extractions/get) until status is `completed` or `failed`.
    </Info>
  </Tab>

  <Tab title="400 Invalid input">
    ```json theme={null}
    { "error": "invalid_input", "message": "Missing or malformed request body" }
    ```

    Request body is missing or malformed. Ensure all required fields are present.
  </Tab>

  <Tab title="400 Invalid tool type">
    ```json theme={null}
    { "error": "invalid_tool_type", "message": "Unrecognized tool type" }
    ```

    The `toolType` value is not one of the 23 supported tools. See [tool types](#tool-types).
  </Tab>

  <Tab title="401 Unauthenticated">
    ```json theme={null}
    { "error": "unauthenticated", "message": "Missing or invalid API key" }
    ```

    Missing or invalid API key.
  </Tab>

  <Tab title="402 Subscription required">
    ```json theme={null}
    { "error": "no_subscription", "message": "No active subscription" }
    ```

    No active subscription or insufficient credits. Possible error values: `no_subscription`, `subscription_inactive`, `no_credits`, `insufficient_credits`.
  </Tab>

  <Tab title="404 Not Found">
    ```json theme={null}
    { "error": "tweet_not_found", "message": "Tweet not found" }
    ```

    The target tweet does not exist, was deleted, or the ID is invalid.

    ```json theme={null}
    { "error": "user_not_found", "message": "X user not found" }
    ```

    The target user does not exist or is suspended.
  </Tab>

  <Tab title="424 X API Dependency Failed">
    ```json theme={null}
    { "error": "x_api_unavailable", "message": "X data source temporarily unavailable" }
    ```

    Send `xquik-api-contract: 2026-04-29` to receive this status for dependency failures that return `502` by default.
  </Tab>

  <Tab title="429 Rate Limited">
    ```json theme={null}
    { "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 }
    ```

    Wait for the `Retry-After` value before retrying the extraction request.
  </Tab>

  <Tab title="502 X API unavailable">
    ```json theme={null}
    { "error": "x_api_unavailable", "message": "X data source temporarily unavailable" }
    ```

    The read service is temporarily unavailable. Retry with exponential backoff.
  </Tab>
</Tabs>

## Run receipt handoff

Treat the `202 Accepted` body as a run receipt, not as extracted data. Store the
job ID immediately, then poll or list jobs until the job reaches `completed` or
`failed`.

```json theme={null}
{
  "extraction_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "tool_type": "reply_extractor",
  "status": "running",
  "receipt_format": "extraction_job",
  "poll_path": "/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "inventory_path": "/api/v1/extractions?status=completed&toolType=reply_extractor",
  "export_path_after_complete": "/api/v1/extractions/a1b2c3d4-e5f6-7890-abcd-ef1234567890/export?format=csv"
}
```

<CardGroup cols={2}>
  <Card title="Receipt fields" icon="clipboard-check">
    Store `id`, `toolType`, and `status`. Do not wait for `results`,
    `totalResults`, `createdAt`, `hasMore`, or `nextCursor` in this response.
  </Card>

  <Card title="Poll results" icon="rotate-cw">
    Use [Get Extraction](/api-reference/extractions/get) with the returned `id`
    to read `job.status`, paginated `results`, `hasMore`, and `nextCursor`.
  </Card>

  <Card title="Find later" icon="list">
    Use [List Extractions](/api-reference/extractions/list) with `status` and
    `toolType` filters when a worker needs to resume from job inventory.
  </Card>

  <Card title="Export after completion" icon="download">
    Use [Export Extraction](/api-reference/extractions/export) after the detail
    response reports `job.status` as `completed`.
  </Card>
</CardGroup>

<Note>
  **Next steps:** [Get Extraction](/api-reference/extractions/get) to retrieve results with pagination, [Export Extraction](/api-reference/extractions/export) to download as CSV/XLSX/Markdown, or [Estimate Extraction](/api-reference/extractions/estimate) to check costs before running.
</Note>