> ## Documentation Index > Fetch the complete documentation index at: https://docs.socq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Twitter User Search > Search public X user accounts by keyword. # Twitter User Search Search public X user accounts by keyword, returning normalized identity, bio, verified status, and audience metrics. ```json theme={"system"} { "query": "OpenAI", "results_limit": 20 } ``` ## Use with MCP | Interface | Value | | -------------- | ------------------------------------------------ | | REST | `POST /v1/x/search-users` | | Compact MCP | `socq_execute` with `endpoint: "x/search-users"` | | Typed MCP | `socq_x_search_users` | | Exact-tool URL | `https://api.socq.ai/mcp?tools=x_search_users` | | CLI | `socq x search-users` | Use the JSON request body above as the nested `input` object for `socq_execute`, or pass the same fields directly to the typed tool. Typed tools also accept `_wait_seconds`, `_result_limit`, and `_idempotency_key`. A successful submission returns a `task_id`. Continue with `socq_get_task` until the task succeeds, then read normalized records from `results.items`. See [MCP quickstart](/integrations/mcp) for the complete submission and polling flow. ## Result Fields Task results use the stable SocQ fields below. Source-specific field names and formats are normalized without inferring or enriching values that the source did not provide. To request a smaller field set, use `fields` for MCP queries, `_result_fields` for typed tools, or `--result-fields` in the CLI. Declared fields remain present when their value is `null`. | Field | Type | Nullable | Description | | ------------------------- | --------- | -------- | ------------------------------------------------------------------------ | | `id` | `string` | Yes | Unique identifier for this result item. | | `platform` | `string` | No | Platform the result belongs to, such as `instagram` or `linkedin`. | | `resource` | `string` | No | SocQ resource represented by the result, such as `videos` or `comments`. | | `type` | `string` | No | Category of the result item, such as `video`, `post`, or `comment`. | | `url` | `string` | Yes | Public URL of the result item when available. | | `published_at` | `string` | Yes | Time the source item was published, in ISO 8601 format when available. | | `collected_at` | `string` | No | Time SocQ collected or processed this result, in ISO 8601 format. | | `username` | `string` | Yes | Public username or handle of the account. | | `name` | `string` | Yes | Display name of the account or profile. | | `text` | `string` | Yes | Biography or description of the account or profile. | | `avatar_url` | `string` | Yes | URL of the account avatar image. | | `cover_url` | `string` | Yes | URL of the cover image. | | `website` | `string` | Yes | Website associated with the account, company, or advertiser. | | `is_verified` | `boolean` | Yes | Whether the account is verified on the platform. | | `is_private` | `boolean` | Yes | Whether the account is private. | | `location` | `object` | Yes | Geographic location associated with the result. | | `location.name` | `string` | Yes | Human-readable location name. | | `location.city` | `string` | Yes | City name. | | `location.region` | `string` | Yes | Region, state, or province name. | | `location.country` | `string` | Yes | Country or territory name or code. | | `location.latitude` | `number` | Yes | Latitude in decimal degrees. | | `location.longitude` | `number` | Yes | Longitude in decimal degrees. | | `metrics` | `object` | Yes | Counters and measurements available for the result item. | | `metrics.followers_count` | `integer` | Yes | Number of followers. | | `metrics.following_count` | `integer` | Yes | Number of accounts followed. | | `metrics.posts_count` | `integer` | Yes | Number of posts or posts associated with the trend. | ## Completed Task Response ```json theme={"system"} { "code": 200, "data": { "task_id": "A1B2C3D4E5F6G7H8", "status": "succeeded", "public_id": "x/search-users", "result_count": 1, "credits_amount": 0.6, "results": { "limit": 1, "next_cursor": null, "has_more": false, "schema_id": "account", "schema_version": "1.0", "items": [ { "id": "4398626122", "platform": "x", "resource": "search-users", "type": "profile", "url": "https://x.com/OpenAI", "published_at": "2015-12-06T22:51:08Z", "collected_at": "2026-09-12T07:00:00Z", "username": "OpenAI", "name": "OpenAI", "text": "OpenAI’s mission is to ensure that artificial general intelligence benefits all of humanity. We’re hiring: https://t.co/dJGr6LgzPA", "avatar_url": "https://pbs.twimg.com/profile_images/1885410181409820672/ztsaR0JW_normal.jpg", "cover_url": "https://pbs.twimg.com/profile_banners/4398626122/1777662919", "website": "https://t.co/3bPlZZkvdL", "is_verified": true, "is_private": false, "location": null, "metrics": { "followers_count": 5321779, "following_count": 4, "posts_count": 2125 } } ] } } } ``` ## OpenAPI ````yaml api-manual/agent-api/agent-api.json POST /v1/x/search-users openapi: 3.1.0 info: title: SocQ Agent API version: v1-c801a6d1844b description: Asynchronous social data API generated from the SocQ Capability Registry. servers: - url: https://api.socq.ai security: [] paths: /v1/x/search-users: post: tags: - x summary: Twitter User Search API description: >- Search public X user accounts by keyword, returning normalized identity, bio, verified status, and audience metrics. operationId: socq_x_search_users requestBody: required: true content: application/json: schema: $schema: https://json-schema.org/draft/2020-12/schema type: object additionalProperties: false properties: callback_url: type: string format: uri query: type: string minLength: 1 description: Search query. results_limit: type: integer minimum: 20 maximum: 2000 default: 20 multipleOf: 20 required: - query responses: '200': description: Task accepted content: application/json: schema: $ref: '#/components/schemas/AgentSubmitResponse' '422': description: Input validation failed content: application/json: schema: $ref: '#/components/schemas/AgentValidationErrorResponse' security: - bearerAuth: [] - apiKeyAuth: [] components: schemas: AgentSubmitResponse: type: object properties: code: type: integer const: 200 data: type: object properties: task_id: type: string status: type: string created_time: type: - string - 'null' required: - task_id - status AgentValidationErrorResponse: type: object properties: code: type: integer const: 422 error: type: object properties: message: type: string type: type: string details: type: object required: - message - type required: - code - error securitySchemes: bearerAuth: type: http scheme: bearer apiKeyAuth: type: apiKey in: header name: x-api-key ````