# Search X Posts

Search X (Twitter) posts by keyword, paged by cursor.

ID: task:twitter_search_posts_v1 · Region: global · Status: available

catalog_version: 938eb1e3bdb6476050bf2983e6e8db1edcf9f0942d16c7ebd2029dcd28295afe
updated_at: 2026-10-21T10:40:52.196893+00:00

X (Twitter)

Dataset releases define historical periods; live reads describe request-time data and do not guarantee completeness.

Docs: https://docs.kleardata.ai/capabilities/task%3Atwitter_search_posts_v1

## GET /v1/collections/tasks/twitter_search_posts_v1

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.



Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "examples": [
    {
      "keyword": "robot vacuum"
    }
  ],
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "cursor": {
        "default": "",
        "maxLength": 4096,
        "type": "string"
      },
      "keyword": {
        "maxLength": 100,
        "minLength": 1,
        "type": "string",
        "ui_default": ""
      },
      "search_type": {
        "default": "Top",
        "enum": [
          "Top",
          "Latest"
        ],
        "type": "string"
      }
    },
    "required": [
      "keyword"
    ],
    "type": "object"
  }
}
```

- input_schema (object): No field description available
- examples (array<object>): No field description available
## describe_collection_task

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.



Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "examples": [
    {
      "keyword": "robot vacuum"
    }
  ],
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "cursor": {
        "default": "",
        "maxLength": 4096,
        "type": "string"
      },
      "keyword": {
        "maxLength": 100,
        "minLength": 1,
        "type": "string",
        "ui_default": ""
      },
      "search_type": {
        "default": "Top",
        "enum": [
          "Top",
          "Latest"
        ],
        "type": "string"
      }
    },
    "required": [
      "keyword"
    ],
    "type": "object"
  }
}
```

- input_schema (object): No field description available
- examples (array<object>): No field description available
## asklear collection describe

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.



Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "examples": [
    {
      "keyword": "robot vacuum"
    }
  ],
  "input_schema": {
    "additionalProperties": false,
    "properties": {
      "cursor": {
        "default": "",
        "maxLength": 4096,
        "type": "string"
      },
      "keyword": {
        "maxLength": 100,
        "minLength": 1,
        "type": "string",
        "ui_default": ""
      },
      "search_type": {
        "default": "Top",
        "enum": [
          "Top",
          "Latest"
        ],
        "type": "string"
      }
    },
    "required": [
      "keyword"
    ],
    "type": "object"
  }
}
```

- input_schema (object): No field description available
- examples (array<object>): No field description available
## POST /v1/collections/estimate

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "description": "Outer transport contract; each registered task validates its own input.",
  "properties": {
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    }
  },
  "required": [
    "task_code",
    "input"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "input": {
    "keyword": "robot vacuum"
  },
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "quote_token": "quote-token-from-estimate",
  "upper_bound_credits": 2
}
```

- quote_token (string): No field description available
- upper_bound_credits (integer): No field description available
## estimate_collection

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "description": "Outer transport contract; each registered task validates its own input.",
  "properties": {
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code",
    "input"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "input": {
    "keyword": "robot vacuum"
  },
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "quote_token": "quote-token-from-estimate",
  "upper_bound_credits": 2
}
```

- quote_token (string): No field description available
- upper_bound_credits (integer): No field description available
## asklear collection estimate

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "description": "Outer transport contract; each registered task validates its own input.",
  "properties": {
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code",
    "input"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "input": {
    "keyword": "robot vacuum"
  },
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "quote_token": "quote-token-from-estimate",
  "upper_bound_credits": 2
}
```

- quote_token (string): No field description available
- upper_bound_credits (integer): No field description available
## POST /v1/collections/jobs

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "quote_token": {
      "maxLength": 4096,
      "minLength": 16,
      "type": "string"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    }
  },
  "required": [
    "task_code",
    "input",
    "quote_token",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "keyword": "robot vacuum"
  },
  "quote_token": "quote-token-from-estimate",
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "job_id": "collection-example",
  "status": "queued"
}
```

- job_id (string): No field description available
- status (string): No field description available

Follow up: GET /v1/collections/jobs/{job_id}
Read job status and its saved public result.

## start_collection

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "quote_token": {
      "maxLength": 4096,
      "minLength": 16,
      "type": "string"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code",
    "input",
    "quote_token",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "keyword": "robot vacuum"
  },
  "quote_token": "quote-token-from-estimate",
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "job_id": "collection-example",
  "status": "queued"
}
```

- job_id (string): No field description available
- status (string): No field description available

Follow up: GET /v1/collections/jobs/{job_id}
Read job status and its saved public result.

## asklear collection start

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

2 Credits per successful task; estimate before starting.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {},
  "additionalProperties": false,
  "properties": {
    "idempotency_key": {
      "maxLength": 128,
      "minLength": 1,
      "type": "string"
    },
    "input": {
      "additionalProperties": false,
      "properties": {
        "cursor": {
          "default": "",
          "maxLength": 4096,
          "type": "string"
        },
        "keyword": {
          "maxLength": 100,
          "minLength": 1,
          "type": "string"
        },
        "search_type": {
          "default": "Top",
          "enum": [
            "Top",
            "Latest"
          ],
          "type": "string"
        }
      },
      "required": [
        "keyword"
      ],
      "type": "object"
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "quote_token": {
      "maxLength": 4096,
      "minLength": 16,
      "type": "string"
    },
    "task_code": {
      "const": "twitter_search_posts_v1"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "task_code",
    "input",
    "quote_token",
    "idempotency_key"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "idempotency_key": "directory-example",
  "input": {
    "keyword": "robot vacuum"
  },
  "quote_token": "quote-token-from-estimate",
  "task_code": "twitter_search_posts_v1"
}
```

### Synthetic response / 合成响应

```json
{
  "job_id": "collection-example",
  "status": "queued"
}
```

- job_id (string): No field description available
- status (string): No field description available

Follow up: GET /v1/collections/jobs/{job_id}
Read job status and its saved public result.

## GET /v1/collections/jobs/{job_id}

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "job_id": {
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "job_id"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "job_id": "collection-example"
}
```

### Response schema / 响应契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "description": "The limited metadata safe to store and expose with a collection result.",
      "properties": {
        "api_name": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        },
        "credits_charged": {
          "maximum": 1000000,
          "minimum": 0,
          "type": "integer"
        },
        "latency_ms": {
          "maximum": 120000,
          "minimum": 0,
          "type": "integer"
        },
        "request_id": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        }
      },
      "required": [
        "request_id",
        "api_name",
        "latency_ms",
        "credits_charged"
      ],
      "type": "object"
    }
  },
  "additionalProperties": true,
  "properties": {
    "result": {
      "additionalProperties": false,
      "properties": {
        "data": {
          "additionalProperties": true,
          "type": "object"
        },
        "meta": {
          "$ref": "#/$defs/Schema1"
        }
      },
      "required": [
        "data",
        "meta"
      ],
      "type": "object"
    }
  },
  "type": "object"
}
```

### Synthetic response / 合成响应

```json
{
  "result": {
    "data": {},
    "meta": {
      "api_name": "https://www.linkedin.com/in/example",
      "credits_charged": 0,
      "latency_ms": 0,
      "request_id": "https://www.linkedin.com/in/example"
    }
  },
  "status": "succeeded"
}
```

- result.meta.request_id (string): Asklear request identifier for tracing.
- result.meta.api_name (string): Executed collection operation name.
- result.meta.latency_ms (integer): Collection execution latency in milliseconds.
- result.meta.credits_charged (integer): Asklear user-side Credits settled for this task after completion.
- result.data.items (array<object>): Projected public items for this task.
- result.data.item_count (integer): Number of returned items.
- result.data.items[].tweet_id (scalar|null): Post identifier, when available.
- result.data.items[].text (scalar|null): Text content, when available.
- result.data.items[].published_at (integer|null): Publication time, when available.
- result.data.items[].language (scalar|null): Language, when available.
- result.data.items[].like_count (scalar|null): Like count, when available.
- result.data.items[].repost_count (scalar|null): Repost count, when available.
- result.data.items[].reply_count (scalar|null): Reply count, when available.
- result.data.items[].quote_count (scalar|null): Quote count, when available.
- result.data.items[].bookmark_count (scalar|null): Bookmark count, when available.
- result.data.items[].view_count (scalar|null): View count, when available.
- result.data.items[].is_sensitive (scalar|null): Is sensitive, when available.
- result.data.items[].conversation_id (scalar|null): Conversation id, when available.
- result.data.items[].in_reply_to_tweet_id (scalar|null): In reply to tweet id, when available.
- result.data.items[].author_id (scalar|null): Author identifier, when available.
- result.data.items[].author_name (scalar|null): Author display name, when available.
- result.data.items[].author_handle (scalar|null): Author handle, when available.
- result.data.has_more (boolean): Whether a continuation is available.
- result.data.next_cursor (string|null): Cursor for the next page, or null.
## get_collection_job

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "job_id": {
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "job_id"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "job_id": "collection-example"
}
```

### Response schema / 响应契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "description": "The limited metadata safe to store and expose with a collection result.",
      "properties": {
        "api_name": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        },
        "credits_charged": {
          "maximum": 1000000,
          "minimum": 0,
          "type": "integer"
        },
        "latency_ms": {
          "maximum": 120000,
          "minimum": 0,
          "type": "integer"
        },
        "request_id": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        }
      },
      "required": [
        "request_id",
        "api_name",
        "latency_ms",
        "credits_charged"
      ],
      "type": "object"
    }
  },
  "additionalProperties": true,
  "properties": {
    "result": {
      "additionalProperties": false,
      "properties": {
        "data": {
          "additionalProperties": true,
          "type": "object"
        },
        "meta": {
          "$ref": "#/$defs/Schema1"
        }
      },
      "required": [
        "data",
        "meta"
      ],
      "type": "object"
    }
  },
  "type": "object"
}
```

### Synthetic response / 合成响应

```json
{
  "result": {
    "data": {},
    "meta": {
      "api_name": "https://www.linkedin.com/in/example",
      "credits_charged": 0,
      "latency_ms": 0,
      "request_id": "https://www.linkedin.com/in/example"
    }
  },
  "status": "succeeded"
}
```

- result.meta.request_id (string): Asklear request identifier for tracing.
- result.meta.api_name (string): Executed collection operation name.
- result.meta.latency_ms (integer): Collection execution latency in milliseconds.
- result.meta.credits_charged (integer): Asklear user-side Credits settled for this task after completion.
- result.data.items (array<object>): Projected public items for this task.
- result.data.item_count (integer): Number of returned items.
- result.data.items[].tweet_id (scalar|null): Post identifier, when available.
- result.data.items[].text (scalar|null): Text content, when available.
- result.data.items[].published_at (integer|null): Publication time, when available.
- result.data.items[].language (scalar|null): Language, when available.
- result.data.items[].like_count (scalar|null): Like count, when available.
- result.data.items[].repost_count (scalar|null): Repost count, when available.
- result.data.items[].reply_count (scalar|null): Reply count, when available.
- result.data.items[].quote_count (scalar|null): Quote count, when available.
- result.data.items[].bookmark_count (scalar|null): Bookmark count, when available.
- result.data.items[].view_count (scalar|null): View count, when available.
- result.data.items[].is_sensitive (scalar|null): Is sensitive, when available.
- result.data.items[].conversation_id (scalar|null): Conversation id, when available.
- result.data.items[].in_reply_to_tweet_id (scalar|null): In reply to tweet id, when available.
- result.data.items[].author_id (scalar|null): Author identifier, when available.
- result.data.items[].author_name (scalar|null): Author display name, when available.
- result.data.items[].author_handle (scalar|null): Author handle, when available.
- result.data.has_more (boolean): Whether a continuation is available.
- result.data.next_cursor (string|null): Cursor for the next page, or null.
## asklear collection get-job

legacy · unavailable · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

search_type 只接受 Top 与 Latest。
要取某条推文的详情用 twitter_tweet_detail_v1。

Existing pricing applies; metadata reads do not charge Credits.

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "properties": {
    "job_id": {
      "type": "string"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "job_id"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "job_id": "collection-example"
}
```

### Response schema / 响应契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "description": "The limited metadata safe to store and expose with a collection result.",
      "properties": {
        "api_name": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        },
        "credits_charged": {
          "maximum": 1000000,
          "minimum": 0,
          "type": "integer"
        },
        "latency_ms": {
          "maximum": 120000,
          "minimum": 0,
          "type": "integer"
        },
        "request_id": {
          "maxLength": 128,
          "minLength": 1,
          "pattern": "^[\\x21-\\x7e]+$",
          "type": "string"
        }
      },
      "required": [
        "request_id",
        "api_name",
        "latency_ms",
        "credits_charged"
      ],
      "type": "object"
    }
  },
  "additionalProperties": true,
  "properties": {
    "result": {
      "additionalProperties": false,
      "properties": {
        "data": {
          "additionalProperties": true,
          "type": "object"
        },
        "meta": {
          "$ref": "#/$defs/Schema1"
        }
      },
      "required": [
        "data",
        "meta"
      ],
      "type": "object"
    }
  },
  "type": "object"
}
```

### Synthetic response / 合成响应

```json
{
  "result": {
    "data": {},
    "meta": {
      "api_name": "https://www.linkedin.com/in/example",
      "credits_charged": 0,
      "latency_ms": 0,
      "request_id": "https://www.linkedin.com/in/example"
    }
  },
  "status": "succeeded"
}
```

- result.meta.request_id (string): Asklear request identifier for tracing.
- result.meta.api_name (string): Executed collection operation name.
- result.meta.latency_ms (integer): Collection execution latency in milliseconds.
- result.meta.credits_charged (integer): Asklear user-side Credits settled for this task after completion.
- result.data.items (array<object>): Projected public items for this task.
- result.data.item_count (integer): Number of returned items.
- result.data.items[].tweet_id (scalar|null): Post identifier, when available.
- result.data.items[].text (scalar|null): Text content, when available.
- result.data.items[].published_at (integer|null): Publication time, when available.
- result.data.items[].language (scalar|null): Language, when available.
- result.data.items[].like_count (scalar|null): Like count, when available.
- result.data.items[].repost_count (scalar|null): Repost count, when available.
- result.data.items[].reply_count (scalar|null): Reply count, when available.
- result.data.items[].quote_count (scalar|null): Quote count, when available.
- result.data.items[].bookmark_count (scalar|null): Bookmark count, when available.
- result.data.items[].view_count (scalar|null): View count, when available.
- result.data.items[].is_sensitive (scalar|null): Is sensitive, when available.
- result.data.items[].conversation_id (scalar|null): Conversation id, when available.
- result.data.items[].in_reply_to_tweet_id (scalar|null): In reply to tweet id, when available.
- result.data.items[].author_id (scalar|null): Author identifier, when available.
- result.data.items[].author_name (scalar|null): Author display name, when available.
- result.data.items[].author_handle (scalar|null): Author handle, when available.
- result.data.has_more (boolean): Whether a continuation is available.
- result.data.next_cursor (string|null): Cursor for the next page, or null.
## POST /v1/search

legacy · available · api_key, oauth

REST requires a customer API Key; MCP requires an enabled authenticated server; CLI requires its published artifact and command.

要取某条推文的详情用 `twitter_tweet_detail_v1`。
首次响应的 pagination.next_page_token 是 asklear-search-cursor-v1. 开头的不透明 Search 令牌；续页原样放入 page_token，保持 search_mode、query、filters 和 page_size 不变。令牌最长 4096 个 ASCII 字符，有效期 24 小时；无效、过期或错绑令牌返回 invalid_query。不要发送上游原始续页值；page 应省略或保持为 1，其他 page 值和 page_size 会被拒绝。Collection 与 /v1/search 共用任务码，但输入与续页契约相互独立；Search 入口通过 /v1/search 使用，Collection 兼容入口使用供应商形输入。

2 Credits per successful task

Where the request declares idempotency_key, reuse it for the same operation; metadata GET is read-only.

A pending response supplies a result/status reference. Read it first; do not automatically resubmit paid execution after a timeout or ambiguous result. Correct 401/403/422 errors before retrying.

### Input schema / 输入契约

```json
{
  "$defs": {
    "Schema1": {
      "additionalProperties": false,
      "description": "Common filter names with source-specific values checked after parsing.\n\n``sort`` stays a bounded string here because ``SearchSourceDefinition``\nowns each provider's vocabulary.",
      "properties": {
        "sort": {
          "enum": [
            "latest",
            "relevance"
          ]
        }
      },
      "required": [],
      "type": "object"
    },
    "Schema2": {
      "additionalProperties": false,
      "description": "Exactly one public image reference accepted by the Search API.",
      "properties": {
        "asset_id": {
          "anyOf": [
            {
              "maxLength": 128,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "base64": {
          "anyOf": [
            {
              "maxLength": 8388608,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        },
        "url": {
          "anyOf": [
            {
              "maxLength": 2048,
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "type": "object"
    }
  },
  "additionalProperties": false,
  "description": "Public request shape shared by text, image, and hybrid sources.",
  "properties": {
    "filters": {
      "$ref": "#/$defs/Schema1"
    },
    "image": {
      "anyOf": [
        {
          "$ref": "#/$defs/Schema2"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "max_credits": {
      "anyOf": [
        {
          "exclusiveMinimum": 0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null
    },
    "page": {
      "const": 1
    },
    "page_token": {
      "default": "",
      "maxLength": 8192,
      "type": "string"
    },
    "query": {
      "anyOf": [
        {
          "maxLength": 200,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "maxLength": 100
    },
    "search_mode": {
      "enum": [
        "text"
      ]
    },
    "source": {
      "const": "twitter"
    },
    "task_query": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Optional task attribution: when provided, write one concise, self-contained task_query in the user's language and reuse that exact value in every call for the task, including discovery, search, approval retry, results, export, and status checks. For MCP calls, when omitted, Asklear records a generic non-user-specific attribution so compatible clients can still call the tool. REST calls may omit it and remain unattributed. It is a task description, not a task identifier. Do not include hidden reasoning, credentials, or direct personal identifiers such as phone numbers, email addresses, identity numbers, or street addresses.",
      "maxLength": 300
    }
  },
  "required": [
    "source",
    "query"
  ],
  "type": "object"
}
```

### Synthetic request / 合成请求

```json
{
  "filters": {},
  "page": 1,
  "query": "示例关键词",
  "search_mode": "text",
  "source": "twitter"
}
```

### Synthetic response / 合成响应

```json
{
  "data": {
    "items": [],
    "pagination": {
      "has_more": false
    }
  }
}
```

- data.items (array<object>): Public Search results returned by this page.
- data.items[].entity_id (string): Stable public identifier for the result.
- data.items[].title (string|null): No title in this phase; the unified field remains nullable string.
- data.items[].url (string|null): No reliable public URL in this phase; the unified field remains nullable string.
- data.items[].snippet (string|null): Public text snippet, populated from the post text.
- data.items[].text (string|null): Post text when supplied.
- data.items[].published_at (integer|null): Publication time as Unix seconds.
- data.items[].like_count (integer|null): Like count.
- data.items[].repost_count (integer|null): Repost count.
- data.items[].comment_count (integer|null): Comment count, mapped from reply_count.
- data.items[].quote_count (integer|null): Quote count.
- data.items[].bookmark_count (integer|null): Bookmark count.
- data.items[].view_count (integer|null): View count.
- data.items[].author_id (string|null): Author identifier.
- data.items[].author_name (string|null): Author display name.
- data.pagination.has_more (boolean): Whether another public Search page is available.
- data.pagination.next_page_token (string|null): Opaque continuation token for page_token; tokens start with asklear-search-cursor-v1.

Follow up: GET /v1/search/{job_id}
Read a pending search and its public results.