> ## Documentation Index
> Fetch the complete documentation index at: https://x-preview-mintlify-1d19a122.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Quickstart guide for searching X Spaces by keyword with the X API v2 standard tier Spaces search endpoint, covering authentication and example calls.

export const Button = ({href, children}) => {
  return <div className="not-prose group">
    <a href={href}>
      <button className="flex items-center space-x-2.5 py-1 px-4 bg-primary-dark dark:bg-white text-white dark:text-gray-950 rounded-full group-hover:opacity-[0.9] font-medium">
        <span>
          {children}
        </span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

This guide walks you through searching for Spaces by keyword.

<Note>
  **Prerequisites**

  Before you begin, you'll need:

  * A [developer account](https://developer.x.com/en/portal/petition/essential/basic-info) with an approved App
  * Your App's Bearer Token
</Note>

***

## Search for Spaces

Search for Spaces matching a keyword:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?\
  query=AI&\
  space.fields=title,host_ids,participant_count,state&\
  state=live" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search for Spaces
  response = client.spaces.search(
      query="AI",
      space_fields=["title", "host_ids", "participant_count", "state"],
      state="live"
  )

  for space in response.data:
      print(f"{space.title} - {space.participant_count} participants")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search for Spaces
  const response = await client.spaces.search({
    query: "AI",
    spaceFields: ["title", "host_ids", "participant_count", "state"],
    state: "live",
  });

  response.data?.forEach((space) => {
    console.log(`${space.title} - ${space.participant_count} participants`);
  });
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "data": [
    {
      "id": "1DXxyRYNejbKM",
      "state": "live",
      "title": "Discussing AI and the Future",
      "host_ids": ["2244994945"],
      "participant_count": 245
    },
    {
      "id": "1YqJDqWYNQDGW",
      "state": "live",
      "title": "AI in Healthcare",
      "host_ids": ["783214"],
      "participant_count": 89
    }
  ],
  "meta": {
    "result_count": 2
  }
}
```

***

## Filter by state

Search only live or scheduled Spaces:

### Live Spaces only

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?query=tech&state=live" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search live Spaces only
  response = client.spaces.search(query="tech", state="live")

  for space in response.data:
      print(f"LIVE: {space.title}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search live Spaces only
  const response = await client.spaces.search({
    query: "tech",
    state: "live",
  });

  response.data?.forEach((space) => {
    console.log(`LIVE: ${space.title}`);
  });
  ```
</CodeGroup>

### Scheduled Spaces only

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?query=tech&state=scheduled" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search scheduled Spaces only
  response = client.spaces.search(query="tech", state="scheduled")

  for space in response.data:
      print(f"SCHEDULED: {space.title}")
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search scheduled Spaces only
  const response = await client.spaces.search({
    query: "tech",
    state: "scheduled",
  });

  response.data?.forEach((space) => {
    console.log(`SCHEDULED: ${space.title}`);
  });
  ```
</CodeGroup>

***

## Include host information

Expand host user data:

<CodeGroup dropdown>
  ```bash cURL theme={null}
  curl "https://api.x.com/2/spaces/search?\
  query=AI&\
  space.fields=title,host_ids,state&\
  expansions=host_ids&\
  user.fields=username,verified" \
    -H "Authorization: Bearer $BEARER_TOKEN"
  ```

  ```python Python SDK theme={null}
  from xdk import Client

  client = Client(bearer_token="YOUR_BEARER_TOKEN")

  # Search with host info
  response = client.spaces.search(
      query="AI",
      space_fields=["title", "host_ids", "state"],
      expansions=["host_ids"],
      user_fields=["username", "verified"]
  )

  for space in response.data:
      print(f"{space.title}")
  # Host info is in response.includes.users
  ```

  ```javascript JavaScript SDK theme={null}
  import { Client } from "@xdevplatform/xdk";

  const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

  // Search with host info
  const response = await client.spaces.search({
    query: "AI",
    spaceFields: ["title", "host_ids", "state"],
    expansions: ["host_ids"],
    userFields: ["username", "verified"],
  });

  response.data?.forEach((space) => {
    console.log(space.title);
  });
  // Host info is in response.includes?.users
  ```
</CodeGroup>

***

## Common parameters

| Parameter      | Description                           |
| :------------- | :------------------------------------ |
| `query`        | Search query (required)               |
| `state`        | Filter: `live`, `scheduled`, or `all` |
| `max_results`  | Results to return (1-100)             |
| `space.fields` | Space fields to include               |
| `expansions`   | Related objects to include            |
| `user.fields`  | User fields to include                |

***

## Next steps

<CardGroup cols={2}>
  <Card title="Space lookup" icon="microphone" href="/x-api/spaces/lookup/quickstart">
    Look up Spaces by ID
  </Card>

  <Card title="API Reference" icon="code" href="/x-api/spaces/search-spaces">
    Full endpoint documentation
  </Card>
</CardGroup>