Skip to main content

Migrating from the Agent API

The Agent API is GraphQL: one endpoint, GenSearch mutations, and polling or multipart/mixed subscriptions. The SuperAnalyst API is REST: resource URLs, JSON bodies, and Server-Sent Events. The two run side by side, so you can move one workflow at a time.

What changes​

Agent APISuperAnalyst API
EndpointPOST https://api.alpha-sense.com/gqlResource paths under https://api.research.alpha-sense.com/superanalyst/v1
Tokenapi.alpha-sense.com/auth (password) or SSO refresh tokenauth.research.alpha-sense.com/oauth/token (refresh token). Agent API tokens also work.
HeadersAuthorization, x-api-key, clientidAuthorization only
EntitlementAPI accessSuperAnalyst and SuperAnalyst API access
Ask a questiongenSearch.auto (or another mode)POST /sessions
Follow upThe same mutation with conversationIdPOST /sessions/{session_id}/messages
Wait for answerPoll progress until 1.0Poll status, or stream events
StreaminggenSearchFast subscription, multipart/mixedtext/event-stream
Answermarkdown with inline [[N • Source]] citationsMarkdown text plus a separate citations list
ErrorsGraphQL errors or conversation.error.codeHTTP status and a JSON error; failed turns show in status
FilesNoneReports, dashboards, slides, and spreadsheets as artifacts

Concept map​

Agent APISuperAnalyst API
Conversation idSession id (URL-encode it in paths)
progress from 0.0 to 1.0status: queued, in_progress, then completed or another end state
conversation.error.codeSession error.code
GenSearchConversationCreatesession.created event
GenSearchResponseMarkdownAppendmessage.delta event
GenSearchResponseMarkdownSetNone. Deltas only append.
Citations parsed out of markdowncitation.added events and each message's citations
Thread history queryGET /sessions/{session_id}/messages
NonePOST /sessions/{session_id}/cancel and GET /sessions

Before and after​

The same task in both APIs: ask a question and print the answer. headers and api hold your credentials, as set up in each API's quick start.

import time
import requests

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

start = requests.post(GQL_URL, headers=headers, json={
"query": "mutation($input: GenSearchInput!) { genSearch { auto(input: $input) { id } } }",
"variables": {"input": {"prompt": "What were the key themes in NVIDIA's latest earnings call?"}},
})
conversation_id = start.json()["data"]["genSearch"]["auto"]["id"]

while True:
time.sleep(2)
poll = requests.post(GQL_URL, headers=headers, json={
"query": "query($id: String!) { genSearch { conversation(id: $id) { markdown progress error { code } } } }",
"variables": {"id": conversation_id},
})
conversation = poll.json()["data"]["genSearch"]["conversation"]
if conversation["error"] or conversation["progress"] >= 1.0:
break

print(conversation["markdown"])

Modes and filters​

There are no GenSearch modes (fast, thinkLonger, deepResearch) or search filters. SuperAnalyst plans its own research. Put any scope, such as sources, companies, or dates, in your question.

Coming soon​

  • On Behalf Of requests. Until then, each token acts as its own user.
  • Credits consumed by each turn.

Migration checklist​

  1. Get a client ID, client secret, and refresh token from the API Keys page. If you use SSO Authentication, you already have them.
  2. Ask your account team to enable SuperAnalyst and SuperAnalyst API access for each user.
  3. Send only Authorization: Bearer <token>. Drop x-api-key and clientid.
  4. Replace each GenSearch mutation with POST /sessions, and each follow-up with POST /sessions/{session_id}/messages. Move any filters into the question text.
  5. Replace progress polling with status polling or streaming.
  6. Replace your citation regex with the citations list. Its text_ranges say where the text cites each source. See Citations.
  7. Branch on the HTTP status and error.code. A failed turn returns 200 with status: "failed".
  8. Don't blindly resend a create or follow-up after a timeout. Check the session first.