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.

Which authentication flow?

This quickstart uses username and password auth. If you sign in with SSO (no AlphaSense password), follow SSO Authentication instead — your account team must enable that beta flow, and you will use a refresh token from the API Keys page.

Prerequisite​

  • An AlphaSense API account with API access. For this guide you need an API key, client ID, client secret, email, and password (username/password sign-in).

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 a few 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.
Workflow AgentsRun pre-built AlphaSense Agent and your own custom agents by id instead of writing prompts.
On Behalf Of RequestsUse a service account to call the API as one of your end users, with their entitlements and usage.
Model Context Protocol (MCP)Connect the AlphaSense Agent API to other applications that support MCP for tool use.
Credit Usage DashboardAdmins: monitor org-wide AI credit spend, projections, and per-user usage in the web app.
Credit Usage APIPull the same usage data programmatically for reporting and alerts.
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.