Skip to main content

Modes and Inputs

GenSearch is AlphaSense's AI-powered research tool that lets you ask natural language questions and receive comprehensive, source-backed answers drawn from AlphaSense's extensive content library. GenSearch operates through a GraphQL API and offers four distinct modes, each designed for a different depth of analysis and response time. You initiate a query with a mutation, then poll for results until the response is complete.

Mode Comparison​

ModeCreditsResponse TimeBest For
fast10 credits~30sQuick answers, real-time queries, simple lookups
auto10 credits~30-90sRecommended default — automatically balances speed and depth
thinkLonger25 credits~60-90sDeeper analysis, nuanced questions, multi-factor comparisons
deepResearch100 credits~12-15minComprehensive research reports, detailed competitive analysis, investment memos

Authentication​

All GenSearch requests require authentication. First obtain a bearer token, then include it alongside your API key and client ID in every request.

import os
import requests

auth_response = requests.post( "https://api.alpha-sense.com/auth", headers={ "x-api-key":
os.environ["ALPHASENSE_API_KEY"], "Content-Type": "application/x-www-form-urlencoded", }, data={
"grant_type": "password", "username": os.environ["ALPHASENSE_EMAIL"], "password":
os.environ["ALPHASENSE_PASSWORD"], "client_id": os.environ["ALPHASENSE_CLIENT_ID"], "client_secret":
os.environ["ALPHASENSE_CLIENT_SECRET"], }, )

token = auth_response.json()["access_token"]

GenSearchInput Schema​

Before building a request, here is the full shape of the input object accepted by every GenSearch mode. Only prompt is required — everything else is optional.

variables = {
    "input": {
        # Optional: continue an existing conversation (follow-up question)
        # Omit or set to None for a new conversation
        "conversationId": None,

        # Required: your search query
        "prompt": "Your search question here",

        # Optional: focus on specific documents (AskInDoc)
        # Cannot be combined with "filters" — use one or the other
        "documents": [
            {"id": "document-id-here"}
        ],

        # Optional: narrow your search results
        "filters": {
            "sources": {"ids": ["source-id"]},
            "industries": ["401020"],
            "expertInsightsFilters": {
                "analystPerspectives": ["Investor-Led (Sell-Side)"],
                "expertPerspectives": ["Medical Professional"],
                "expertTranscriptType": ["Company Deep-Dive"]
            },
            "documentAuthors": ["Author Name"],
            "date": {
                "customRange": {"from": "2025-01-01", "to": "2025-06-30"},
                # OR use a preset instead:
                # "preset": "LAST_90_DAYS"
            },
            "countries": ["US", "CA"],
            "companies": {
                "include": ["AAPL", "MSFT"],
                # OR use a watchlist instead:
                # "watchlists": ["watchlist-id"]
            }
        },

        # Optional: include web search results
        "useWebSearch": True
    }
}
documents and filters are mutually exclusive

You can use documents (AskInDoc) or filters, but not both in the same request.

Key rules:

  • conversationId is optional — omit it or pass None for a new conversation; pass the id returned by a previous GenSearch mutation to ask a follow-up question in the same thread
  • prompt is the only required field
  • Within filters, combine as many fields as you want — they use AND logic (every filter narrows the results further)
  • For date, use either customRange or preset, not both
  • companies.include and companies.watchlists cannot be combined — use one or the other
  • useWebSearch lives at the input level, not inside filters

Search Filters​

Each filter can be used on its own or combined with others. For GraphQL lookups, enums, and external references for the IDs and codes used below, see Utility APIs.

Source Filters​

Filter results by document source type — broker research, SEC filings, earnings transcripts, news, and more.

"filters": {
    "sources": {"ids": ["31019"]}  # Broker Research
}

Look up source IDs with the filingTypesV3 query. See Utility APIs — Source Types.

Industry Filters (GICS)​

Narrow results to specific industries using GICS codes.

"filters": {
    "industries": ["401020"]  # Insurance
}

GICS codes follow the Global Industry Classification Standard. See MSCI’s overview for structure and definitions: The Global Industry Classification Standard (GICS). For how these map to GenSearch, see Utility APIs — Industry Codes.

Expert Insights Filters​

Filter within AlphaSense Expert Insights content using three sub-fields:

  • analystPerspectives — type of analyst viewpoint (e.g., "Investor-Led (Sell-Side)")
  • expertPerspectives — type of expert (e.g., "Medical Professional")
  • expertTranscriptType — transcript format (e.g., "Company Deep-Dive")
"filters": {
    "expertInsightsFilters": {
        "expertPerspectives": ["Medical Professional"],
        "expertTranscriptType": ["Company Deep-Dive"]
    }
}

See Utility APIs — Expert Insights Filters for available values.

Document Author Filters​

Filter by the author of documents uploaded to the AlphaSense platform. This applies to user-uploaded content (internal research, reports your team has added, etc.).

"filters": {
    "documentAuthors": ["Jane Smith"]
}

Date Filters​

Restrict results to a time window. Use either a preset or a custom range, not both.

Presets:

Preset ValueRange
LAST_24_HOURSPast 24 hours
LAST_7_DAYSPast 7 days
LAST_30_DAYSPast 30 days
LAST_90_DAYSPast 90 days
LAST_6_MONTHSPast 6 months
LAST_12_MONTHSPast 12 months
LAST_18_MONTHSPast 18 months
LAST_2_YEARSPast 2 years
# Preset
"filters": {
    "date": {"preset": "LAST_90_DAYS"}
}

# Custom range (YYYY-MM-DD)
"filters": {
    "date": {"customRange": {"from": "2025-01-01", "to": "2025-03-31"}}
}

See Utility APIs — Date Presets for the full enum reference.

Country Filters​

Filter by country using uppercase 2-letter ISO country codes. Use "US*" for US non-domicile entities.

"filters": {
    "countries": ["US", "GB", "CA"]
}

Country codes are ISO 3166-1 alpha-2 values. See Wikipedia — ISO 3166-1 alpha-2 for the code list, and Utility APIs — Country Codes for GenSearch usage notes.

Company Filters​

Focus results on specific companies by ticker/identifier, or by a saved watchlist.

# By ticker or identifier
"filters": {
    "companies": {"include": ["AAPL", "MSFT", "GOOGL"]}
}

# By watchlist
"filters": {
    "companies": {"watchlists": ["your-watchlist-id"]}
}
warning

You cannot combine include and watchlists in the same request — use one or the other.

Look up company identifiers with the companies query and watchlist IDs with the user query. See Utility APIs — Company Lookup and Utility APIs — User Watchlists.

AskInDoc​

Point GenSearch at one or more specific documents so the response is grounded entirely in those docs. This is useful when you have already found a document (such as a 10-K, earnings transcript, or research report) and want to ask targeted questions about it.

warning

When using documents, do not include the filters object. They cannot be combined in the same request.

Single document:

variables = {
    "input": {
        "prompt": "What are the key risk factors mentioned in this filing?",
        "documents": [
            {"id": "abc123-document-id"}
        ]
    }
}

Multiple documents:

variables = {
    "input": {
        "prompt": "Compare the revenue guidance across these earnings calls.",
        "documents": [
            {"id": "earnings-call-q1-id"},
            {"id": "earnings-call-q2-id"},
            {"id": "earnings-call-q3-id"}
        ]
    }
}

Document IDs can be found using the Document Search API. See Utility APIs — Document Search for a lookup example.

Set useWebSearch to true to include public web results alongside AlphaSense content. This field lives at the input level, not inside filters.

variables = {
    "input": {
        "prompt": "What are the latest developments in quantum computing?",
        "useWebSearch": True
    }
}

You can combine web search with filters:

variables = {
    "input": {
        "prompt": "Recent moves by TSMC in Arizona",
        "filters": {
            "companies": {"include": ["TSM"]},
            "date": {"preset": "LAST_30_DAYS"}
        },
        "useWebSearch": True
    }
}

Combining Multiple Filters​

Filters use AND logic — every filter you add narrows the results further. Combine as many as you need in a single request.

# Example: sell-side analyst coverage of Apple's AI strategy in the last 6 months
variables = {
    "input": {
        "prompt": "What is Apple's AI and machine learning strategy?",
        "filters": {
            "companies": {"include": ["AAPL"]},
            "sources": {"ids": ["31019"]},
            "date": {"preset": "LAST_6_MONTHS"},
            "expertInsightsFilters": {
                "analystPerspectives": ["Investor-Led (Sell-Side)"]
            }
        }
    }
}
# Example: supply chain analysis for semiconductors in US, China, and Taiwan
variables = {
    "input": {
        "prompt": "Supply chain disruptions and their impact on margins",
        "filters": {
            "industries": ["45301020"],
            "date": {
                "customRange": {
                    "from": "2025-06-01",
                    "to": "2025-12-31"
                }
            },
            "countries": ["US", "CN", "TW"]
        }
    }
}

Fast Mode​

Fast mode is optimized for speed. Use it when you need a quick, concise answer and latency matters more than exhaustive depth. At 10 credits per query and approximately 30 seconds of response time, it is ideal for real-time lookups, simple factual questions, and lightweight integrations.

Mutation​

import os
import requests

url = "https://api.alpha-sense.com/gql" headers = { "x-api-key": os.environ["ALPHASENSE_API_KEY"],
"clientid": os.environ["ALPHASENSE_CLIENT_ID"], "Authorization": f"Bearer {token}", "Content-Type":
"application/json", }

mutation = """ mutation GenSearchFast($input: GenSearchInput!) { genSearch { fast(input: $input) {
id } } } """

variables = { "input": { "prompt": "What was Apple's revenue in Q4 2025?" } }

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

conversation_id = response.json()["data"]["genSearch"]["fast"]["id"] print(f"Conversation ID:
{conversation_id}")

tip

You can add filters, documents, or useWebSearch to the input alongside prompt. See Search Filters.

Auto Mode​

Auto mode is the recommended default for most use cases. It automatically selects the optimal depth of analysis based on your query, balancing speed and thoroughness. At 10 credits per query and approximately 30-90 seconds of response time, it is ideal when you want high-quality results without having to choose between fast and thinkLonger manually.

Mutation​

import os
import requests

url = "https://api.alpha-sense.com/gql" headers = { "x-api-key": os.environ["ALPHASENSE_API_KEY"],
"clientid": os.environ["ALPHASENSE_CLIENT_ID"], "Authorization": f"Bearer {token}", "Content-Type":
"application/json", }

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

variables = { "input": { "prompt": "What are the key trends driving semiconductor demand in 2025?" }
}

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

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

tip

You can add filters, documents, or useWebSearch to the input alongside prompt. See Search Filters.

Think Longer Mode​

Think Longer mode provides a deeper level of analysis. It spends more time reasoning through the question, cross-referencing multiple sources, and producing a more nuanced response. At 25 credits per query and approximately 60-90 seconds of response time, it is well-suited for multi-factor comparisons, strategic questions, and situations where accuracy and completeness outweigh speed.

Mutation​

import os
import requests

url = "https://api.alpha-sense.com/gql" headers = { "x-api-key": os.environ["ALPHASENSE_API_KEY"],
"clientid": os.environ["ALPHASENSE_CLIENT_ID"], "Authorization": f"Bearer {token}", "Content-Type":
"application/json", }

mutation = """ mutation GenSearchThinkLonger($input: GenSearchInput!) { genSearch {
thinkLonger(input: $input) { id } } } """

variables = { "input": { "prompt": "Compare the competitive positioning of NVIDIA and AMD in the
data center GPU market over the past two quarters." } }

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

conversation_id = response.json()["data"]["genSearch"]["thinkLonger"]["id"] print(f"Conversation ID:
{conversation_id}")

tip

You can add filters, documents, or useWebSearch to the input alongside prompt. See Search Filters.

Deep Research Mode​

Deep Research mode produces comprehensive, report-grade output. It performs extensive source gathering, synthesizes information across many documents, and returns a structured, detailed research report. At 100 credits per query and approximately 12-15 minutes of response time, it is designed for investment memos, thorough competitive analyses, and any scenario where you need the most complete answer possible.

Mutation​

import os
import requests

url = "https://api.alpha-sense.com/gql" headers = { "x-api-key": os.environ["ALPHASENSE_API_KEY"],
"clientid": os.environ["ALPHASENSE_CLIENT_ID"], "Authorization": f"Bearer {token}", "Content-Type":
"application/json", }

mutation = """ mutation GenSearchDeepResearch($input: GenSearchInput!) { genSearch {
deepResearch(input: $input) { id } } } """

variables = { "input": { "prompt": "Provide a comprehensive analysis of the electric vehicle market:
key players, supply chain risks, regulatory tailwinds, and projected growth through 2027." } }

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

conversation_id = response.json()["data"]["genSearch"]["deepResearch"]["id"] print(f"Conversation
ID: {conversation_id}")

tip

You can add filters, documents, or useWebSearch to the input alongside prompt. See Search Filters.

Follow-Up Questions​

Every GenSearch mutation returns a conversation id. To ask a follow-up question within the same conversation, pass that id as conversationId in your next mutation. The conversation ID also serves as the thread ID for retrieving the full message history.

Follow-Up Mutation​

# Use the conversation_id from a previous GenSearch mutation response
follow_up_mutation = """
mutation GenSearchAuto($input: GenSearchInput!) {
    genSearch {
        auto(input: $input) {
            id
        }
    }
}
"""

variables = {
    "input": {
        "conversationId": conversation_id,  # ID from the previous mutation
        "prompt": "How does that compare to the previous quarter?"
    }
}

response = requests.post(
    url,
    headers=headers,
    json={"query": follow_up_mutation, "variables": variables},
)

follow_up_id = response.json()["data"]["genSearch"]["auto"]["id"]
print(f"Follow-up conversation ID: {follow_up_id}")

Polling a Follow-Up Response​

The follow-up mutation returns a new conversation id. Poll it with the conversation query — the same approach used for any GenSearch response.

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

variables = {
    "conversationId": follow_up_id,
}

# Poll until progress reaches 1.0
while True:
    response = requests.post(
        url,
        headers=headers,
        json={"query": poll_query, "variables": variables},
    )

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

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

    if conversation["progress"] >= 1.0:
        break

    time.sleep(2)

print(conversation["markdown"])

Retrieving Thread History​

The conversation ID doubles as the thread ID. Use the thread query to retrieve the full message history for a conversation — ideal for chat-like UIs that display the entire exchange. Each message in the thread has its own id (format: xxxxxx__xxxxxxxxxxxxx_xxxxxxxxxxxxx) and contains the original request.prompt and the response.markdown.

query genSearch($threadId: String!) {
  genSearch {
    thread(id: $threadId) {
      id
      messages {
        id
        request {
          prompt
        }
        response {
          error {
            code
          }
          markdown
          progress
        }
      }
    }
  }
}
thread_query = """
query genSearch($threadId: String!) {
    genSearch {
        thread(id: $threadId) {
            id
            messages {
                id
                request { prompt }
                response {
                    error { code }
                    markdown
                    progress
                }
            }
        }
    }
}
"""

# The conversation ID doubles as the thread ID
variables = {
    "threadId": conversation_id,
}

response = requests.post(
    url,
    headers=headers,
    json={"query": thread_query, "variables": variables},
)

thread = response.json()["data"]["genSearch"]["thread"]

print(f"Thread ID: {thread['id']}")
for message in thread["messages"]:
    print(f"\n--- Message {message['id']} ---")
    print(f"Prompt: {message['request']['prompt']}")
    print(f"Response: {message['response']['markdown'][:200]}...")
When to use each approach

Use the conversation query to poll a single follow-up response — same as any other GenSearch poll. Use the thread query when you need the full message history, for example in a chat-like UI that displays the entire exchange.

Polling for Results​

After initiating any GenSearch mode, you receive a conversation ID. Use this ID to poll for results. The polling query is the same regardless of which mode you used. To retrieve the full message history across follow-up questions, see Follow-Up Questions.

Polling Query​

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

Full Polling Implementation​

import os
import time
import requests

url = "https://api.alpha-sense.com/gql" headers = { "x-api-key": os.environ["ALPHASENSE_API_KEY"],
"clientid": os.environ["ALPHASENSE_CLIENT_ID"], "Authorization": f"Bearer {token}", "Content-Type":
"application/json", }

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

def poll_for_results(conversation_id, interval=3, timeout=600): """Poll until the GenSearch
conversation completes or times out.""" start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.post(
            url,
            headers=headers,
            json={
                "query": poll_query,
                "variables": {"conversationId": conversation_id},
            },
        )

        data = response.json()["data"]["genSearch"]["conversation"]

        # Check for errors
        if data.get("error"):
            raise Exception(f"GenSearch error: {data['error']['code']}")

        progress = data.get("progress", 0.0)
        print(f"Progress: {progress:.0%}")

        # progress reaches 1.0 when the response is complete
        if progress >= 1.0:
            return data["markdown"]

        time.sleep(interval)

    raise TimeoutError("Polling timed out waiting for GenSearch results.")

# Usage: pass the conversation_id from any mode's mutation response

result_markdown = poll_for_results(conversation_id) print(result_markdown)

Progress Tracking​

The progress field returned by the polling query is a floating-point number that ranges from 0.0 to 1.0:

Progress ValueMeaning
0.0The request has been received and queued
0.0 < progress < 1.0The response is being generated; partial results may be available in markdown
1.0The response is complete; the final result is in markdown

Recommended polling intervals by mode:

  • fast -- poll every 2-3 seconds (expected completion in ~30 seconds)
  • auto -- poll every 3-5 seconds (expected completion in ~30-90 seconds)
  • thinkLonger -- poll every 5 seconds (expected completion in ~60-90 seconds)
  • deepResearch -- poll every 10 seconds (expected completion in ~12-15 minutes)

While the response is still being generated (progress < 1.0), the markdown field may contain partial content. You can display this to the user as a progressive loading experience or wait for progress to reach 1.0 before rendering the full response.

Response Format​

All GenSearch modes return their results in the markdown field as standard Markdown text with inline citations. Citations follow the pattern:


[[N • Source Name]]

where N is a numeric reference and • is a bullet separator, followed by the Source Name that identifies the document from which the information was drawn. For example:

Apple reported Q4 2025 revenue of $94.9 billion, a 6% year-over-year increase
[[1 • Earnings ]]. The growth was primarily driven by
strong performance in the Services segment [[2 • Broker Research]].

Each citation links back to a specific source document in AlphaSense's content library. For details on how to programmatically parse and render these citations, see the Response Parsing guide.

When to Use Which Mode​

Choosing the right mode depends on the nature of your question, your latency requirements, and how many credits you want to spend.

Use fast when:​

  • You need a quick factual answer (e.g., "What was Tesla's Q3 revenue?")
  • The query is part of a real-time user-facing interface where response time matters
  • You are performing many lookups in batch and want to conserve credits
  • The question has a straightforward, well-scoped answer

Use auto when:​

  • You want the best balance of speed and depth without choosing a mode manually
  • You are building a general-purpose integration and want a single default mode
  • The query complexity varies and you want the system to adapt automatically
  • You want high-quality results at the same credit cost as fast

Use thinkLonger when:​

  • The question requires comparing multiple data points or companies
  • You need a more nuanced answer that weighs different perspectives
  • Accuracy and depth are more important than sub-minute response time
  • Examples: "How do margins at Starbucks compare to Dunkin' over the last four quarters?" or "What are analysts saying about the impact of rising interest rates on REITs?"

Use deepResearch when:​

  • You need a comprehensive, report-style answer covering an entire topic
  • The question spans multiple dimensions (market sizing, competitive landscape, regulatory environment, etc.)
  • You are generating content for investment memos, board presentations, or strategic planning
  • You are willing to wait several minutes and spend more credits for the most thorough response
  • Examples: "Provide a full competitive analysis of the cloud infrastructure market" or "What are the key risks and opportunities in the global semiconductor supply chain?"

Quick Decision Guide​

Do you need the absolute fastest response possible?
  YES --> Use fast
  NO  --> Do you need a comprehensive, report-grade output?
            YES --> Use deepResearch
            NO  --> Do you specifically need extended reasoning for a complex comparison?
                      YES --> Use thinkLonger
                      NO  --> Use auto (recommended default)
Next Steps
  • Streaming: For real-time progressive rendering instead of polling, see the Streaming guide.
  • Response Parsing: To learn how to parse citations and structure the Markdown response for display, see the Response Parsing guide.
  • Workflow Agents: To run pre-built AlphaSense templates or your own saved agents by id instead of writing free-form prompts, see Workflow Agents.
  • Utility APIs: Look up filter values (source IDs, GICS codes, company tickers, etc.) at Utility APIs.