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 API | SuperAnalyst API | |
|---|---|---|
| Endpoint | POST https://api.alpha-sense.com/gql | Resource paths under https://api.research.alpha-sense.com/superanalyst/v1 |
| Token | api.alpha-sense.com/auth (password) or SSO refresh token | auth.research.alpha-sense.com/oauth/token (refresh token). Agent API tokens also work. |
| Headers | Authorization, x-api-key, clientid | Authorization only |
| Entitlement | API access | SuperAnalyst and SuperAnalyst API access |
| Ask a question | genSearch.auto (or another mode) | POST /sessions |
| Follow up | The same mutation with conversationId | POST /sessions/{session_id}/messages |
| Wait for answer | Poll progress until 1.0 | Poll status, or stream events |
| Streaming | genSearchFast subscription, multipart/mixed | text/event-stream |
| Answer | markdown with inline [[N • Source]] citations | Markdown text plus a separate citations list |
| Errors | GraphQL errors or conversation.error.code | HTTP status and a JSON error; failed turns show in status |
| Files | None | Reports, dashboards, slides, and spreadsheets as artifacts |
Concept map
| Agent API | SuperAnalyst API |
|---|---|
Conversation id | Session id (URL-encode it in paths) |
progress from 0.0 to 1.0 | status: queued, in_progress, then completed or another end state |
conversation.error.code | Session error.code |
GenSearchConversationCreate | session.created event |
GenSearchResponseMarkdownAppend | message.delta event |
GenSearchResponseMarkdownSet | None. Deltas only append. |
Citations parsed out of markdown | citation.added events and each message's citations |
| Thread history query | GET /sessions/{session_id}/messages |
| None | POST /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.
- Agent API (before)
- SuperAnalyst API (after)
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"])
import time
from urllib.parse import quote
API_URL = "https://api.research.alpha-sense.com/superanalyst/v1/superanalysts/default"
question = {"input": {"text": "What were the key themes in NVIDIA's latest earnings call?"}}
session = api.post(f"{API_URL}/sessions", json=question).json()
session_url = f"{API_URL}/sessions/{quote(session['id'], safe='')}"
while True:
time.sleep(5)
session = api.get(session_url).json()
if session["status"] not in ("queued", "in_progress"):
break
answer = api.get(f"{session_url}/messages", params={"limit": 1}).json()["data"][0]
print(answer["content"][0]["text"])
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
- Get a client ID, client secret, and refresh token from the API Keys page. If you use SSO Authentication, you already have them.
- Ask your account team to enable SuperAnalyst and SuperAnalyst API access for each user.
- Send only
Authorization: Bearer <token>. Dropx-api-keyandclientid. - Replace each GenSearch mutation with
POST /sessions, and each follow-up withPOST /sessions/{session_id}/messages. Move any filters into the question text. - Replace
progresspolling withstatuspolling or streaming. - Replace your citation regex with the
citationslist. Itstext_rangessay where the text cites each source. See Citations. - Branch on the HTTP status and
error.code. A failed turn returns200withstatus: "failed". - Don't blindly resend a create or follow-up after a timeout. Check the session first.