Skip to main content

Quick Start

Auth to first GenSearch result in under 5 minutes

This guide walks you through authenticating with the AlphaSense Agent API and running your first GenSearch query. By the end you will have a working script that asks a financial question and returns a cited, markdown-formatted answer.

Prerequisite​

  • An AlphaSense API account with credentials (API key, client ID, client secret, email, and password)

Set up your environment variables​

Create a .env file in your project root (or export the variables in your shell) with the following template:

.env
ALPHASENSE_API_KEY=your_api_key_here
ALPHASENSE_CLIENT_ID=your_client_id_here
ALPHASENSE_CLIENT_SECRET=your_client_secret_here
ALPHASENSE_EMAIL=your_email_here
ALPHASENSE_PASSWORD=your_password_here
Don't have credentials?

Contact your account team at support@alpha-sense.com to request API access.

Authenticate​

The AlphaSense API uses OAuth 2.0 password-grant authentication. Send your credentials to the /auth endpoint and receive a Bearer token that is valid for subsequent requests.

import os
import requests

api_key    = os.environ["ALPHASENSE_API_KEY"]
client_id  = os.environ["ALPHASENSE_CLIENT_ID"]
client_secret = os.environ["ALPHASENSE_CLIENT_SECRET"]
email      = os.environ["ALPHASENSE_EMAIL"]
password   = os.environ["ALPHASENSE_PASSWORD"]

auth_response = requests.post(
    "https://api.alpha-sense.com/auth",
    headers={
        "x-api-key": api_key,
        "Content-Type": "application/x-www-form-urlencoded",
    },
    data={
        "grant_type": "password",
        "username": email,
        "password": password,
        "client_id": client_id,
        "client_secret": client_secret,
    },
)
auth_response.raise_for_status()

access_token = auth_response.json()["access_token"]
print("Authenticated successfully.")

Ask a question (GenSearch auto mode)​

Use the genSearch.auto GraphQL mutation to submit a natural-language question. Auto mode automatically selects the best strategy for your query. The mutation returns a conversation id that you use to poll for the answer.

import json

GRAPHQL_URL = "https://api.alpha-sense.com/gql"

mutation = """
mutation GenSearch($input: GenSearchInput!) {
  genSearch {
    auto(input: $input) {
      id
    }
  }
}
"""

variables = {
    "input": {
        "prompt": "What were Apple's key Q4 2024 financial results?"
    }
}

headers = {
    "x-api-key": api_key,
    "clientid": client_id,
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

response = requests.post(
    GRAPHQL_URL,
    headers=headers,
    json={"query": mutation, "variables": variables},
)
response.raise_for_status()

conversation_id = response.json()["data"]["genSearch"]["auto"]["id"]
print(f"GenSearch started — conversation ID: {conversation_id}")

Get your answer​

Poll the genSearch.conversation query until progress reaches 1.0 (or an error is returned). The markdown field contains the full answer with inline citations in the format [[N • Source]].

import time

poll_query = """
query Query($conversationId: String!) {
  genSearch {
    conversation(id: $conversationId) {
      id
      markdown
      progress
      error {
        code
      }
    }
  }
}
"""

while True:
    poll_response = requests.post(
        GRAPHQL_URL,
        headers=headers,
        json={
            "query": poll_query,
            "variables": {"conversationId": conversation_id},
        },
    )
    poll_response.raise_for_status()

    conversation = poll_response.json()["data"]["genSearch"]["conversation"]
    progress = conversation["progress"]
    print(f"Progress: {progress:.0%}")

    if conversation.get("error"):
        raise RuntimeError(f"GenSearch error: {conversation['error']['code']}")

    if progress >= 1.0:
        break

    time.sleep(2)

print("\n--- Answer ---\n")
print(conversation["markdown"])

Complete script (Python)​

Below is a single, copy-paste-ready Python script that combines all three steps. Make sure your environment variables are set before running.

quickstart.py
#!/usr/bin/env python3
"""AlphaSense Agent API — Quickstart (GenSearch auto mode)."""

import os
import time
import requests

# ---------------------------------------------------------------------------
# Configuration (reads from environment variables)
# ---------------------------------------------------------------------------
API_KEY       = os.environ["ALPHASENSE_API_KEY"]
CLIENT_ID     = os.environ["ALPHASENSE_CLIENT_ID"]
CLIENT_SECRET = os.environ["ALPHASENSE_CLIENT_SECRET"]
EMAIL         = os.environ["ALPHASENSE_EMAIL"]
PASSWORD      = os.environ["ALPHASENSE_PASSWORD"]

AUTH_URL       = "https://api.alpha-sense.com/auth"
GRAPHQL_URL    = "https://api.alpha-sense.com/gql"

# ---------------------------------------------------------------------------
# Step 1 — Authenticate
# ---------------------------------------------------------------------------
auth_response = requests.post(
    AUTH_URL,
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/x-www-form-urlencoded",
    },
    data={
        "grant_type": "password",
        "username": EMAIL,
        "password": PASSWORD,
        "client_id": CLIENT_ID,
        "client_secret": CLIENT_SECRET,
    },
)
auth_response.raise_for_status()
access_token = auth_response.json()["access_token"]
print("Step 1 complete — authenticated successfully.\n")

# Shared headers for GraphQL requests
gql_headers = {
    "x-api-key": API_KEY,
    "clientid": CLIENT_ID,
    "Authorization": f"Bearer {access_token}",
    "Content-Type": "application/json",
}

# ---------------------------------------------------------------------------
# Step 2 — Ask a question (GenSearch auto mode)
# ---------------------------------------------------------------------------
mutation = """
mutation GenSearch($input: GenSearchInput!) {
  genSearch {
    auto(input: $input) {
      id
    }
  }
}
"""

variables = {
    "input": {
        "prompt": "What were Apple's key Q4 2024 financial results?"
    }
}

search_response = requests.post(
    GRAPHQL_URL,
    headers=gql_headers,
    json={"query": mutation, "variables": variables},
)
search_response.raise_for_status()

conversation_id = search_response.json()["data"]["genSearch"]["auto"]["id"]
print(f"Step 2 complete — conversation ID: {conversation_id}\n")

# ---------------------------------------------------------------------------
# Step 3 — Poll for the answer
# ---------------------------------------------------------------------------
poll_query = """
query Query($conversationId: String!) {
  genSearch {
    conversation(id: $conversationId) {
      id
      markdown
      progress
      error {
        code
      }
    }
  }
}
"""

while True:
    poll_response = requests.post(
        GRAPHQL_URL,
        headers=gql_headers,
        json={
            "query": poll_query,
            "variables": {"conversationId": conversation_id},
        },
    )
    poll_response.raise_for_status()

    conversation = poll_response.json()["data"]["genSearch"]["conversation"]
    progress = conversation["progress"]
    print(f"  Polling… progress: {progress:.0%}")

    if conversation.get("error"):
        raise RuntimeError(f"GenSearch error: {conversation['error']['code']}")

    if progress >= 1.0:
        break

    time.sleep(2)

print("\nStep 3 complete — answer received.\n")
print("=" * 60)
print(conversation["markdown"])
print("=" * 60)

Run the script:

# Load your .env (if using dotenv-style file)
export $(grep -v '^#' .env | xargs)

python quickstart.py

What's next?​

You have successfully authenticated and retrieved your first GenSearch answer. Here are three paths to explore next:

PathDescription
GenSearch ModesLearn about auto (recommended), fast, thinkLonger, and deepResearch modes and when to use each.
Follow-Up QuestionsPass a conversation ID to ask follow-up questions and retrieve full thread history.
Model Context Protocol (MCP)Connect the AlphaSense Agent API to AI assistants that support MCP for seamless tool use.
LLM-Friendly Docs

This documentation is designed to be read by LLMs. You can point your AI assistant to developer.alpha-sense.com/llms.txt for a machine-readable overview, or simply ask it to fetch any page from this portal for full details and code examples.