Document Search API

Search for specific documents across AlphaSense's database with keyword, date, and company filters. Returns document-level results with text snippets.

GraphQL Query

query SearchDocuments(
  $filter: SearchFilter!
  $limit: Int!
  $sorting: SearchSorting!
  $cursor: String
) {
  search(filter: $filter, limit: $limit, sorting: $sorting, cursor: $cursor) {
    cursor
    totalCount
    documents {
      id
      title
      releasedAt
      snippets(limit: 20) {
        statements {
          text
        }
      }
    }
  }
}

Filter Parameters

Parameter	Type	Description
filter.keyword.query	String	Search keywords
filter.date.preset	Enum	LAST_24_HOURS, LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, LAST_1_YEAR, LAST_2_YEARS
filter.companies.ids	[String]	Company ticker symbols (e.g., ["AAPL"])
filter.types.ids	[String]	Source type IDs (e.g., ["21000"] for Expert Calls)
limit	Int	Max documents to return
sorting.field	Enum	DATE
sorting.direction	Enum	ASC, DESC
cursor	String	Pagination cursor from previous response

Code Examples

Python

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"]

# Authenticate to obtain a bearer token (see Authentication guide)
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"]

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

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

query = """
query SearchDocuments($filter: SearchFilter!, $limit: Int!, $sorting: SearchSorting!, $cursor: String) {
  search(filter: $filter, limit: $limit, sorting: $sorting, cursor: $cursor) {
    cursor
    totalCount
    documents {
      id
      title
      releasedAt
      snippets(limit: 20) {
        statements {
          text
        }
      }
    }
  }
}
"""

variables = {
    "filter": {
        "keyword": {
            "query": "AI strategy"
        },
        "date": {
            "preset": "LAST_30_DAYS"
        }
    },
    "limit": 20,
    "sorting": {
        "field": "DATE",
        "direction": "DESC"
    }
}

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

# Handle the response
results = data["data"]["search"]
print(f"Total documents found: {results['totalCount']}")

for doc in results["documents"]:
    print(f"\n--- {doc['title']} (Released: {doc['releasedAt']}) ---")
    for snippet in doc["snippets"]:
        for statement in snippet["statements"]:
            print(f"  {statement['text']}")

# Store cursor for pagination
next_cursor = results["cursor"]

JavaScript

const API_KEY = process.env.ALPHASENSE_API_KEY
const CLIENT_ID = process.env.ALPHASENSE_CLIENT_ID

// Authenticate to obtain a bearer token (see Authentication guide)
const authResp = await fetch('https://api.alpha-sense.com/auth', {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: new URLSearchParams({
    grant_type: 'password',
    username: process.env.ALPHASENSE_EMAIL,
    password: process.env.ALPHASENSE_PASSWORD,
    client_id: CLIENT_ID,
    client_secret: process.env.ALPHASENSE_CLIENT_SECRET,
  }),
})
const {access_token: ACCESS_TOKEN} = await authResp.json()

const url = 'https://api.alpha-sense.com/gql'

const query = `
query SearchDocuments($filter: SearchFilter!, $limit: Int!, $sorting: SearchSorting!, $cursor: String) {
  search(filter: $filter, limit: $limit, sorting: $sorting, cursor: $cursor) {
    cursor
    totalCount
    documents {
      id
      title
      releasedAt
      snippets(limit: 20) {
        statements {
          text
        }
      }
    }
  }
}
`

const variables = {
  filter: {
    keyword: {
      query: 'AI strategy',
    },
    date: {
      preset: 'LAST_30_DAYS',
    },
  },
  limit: 20,
  sorting: {
    field: 'DATE',
    direction: 'DESC',
  },
}

const response = await fetch(url, {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    clientid: CLIENT_ID,
    Authorization: `Bearer ${ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({query, variables}),
})

const data = await response.json()

// Handle the response
const results = data.data.search
console.log(`Total documents found: ${results.totalCount}`)

for (const doc of results.documents) {
  console.log(`\n--- ${doc.title} (Released: ${doc.releasedAt}) ---`)
  for (const snippet of doc.snippets) {
    for (const statement of snippet.statements) {
      console.log(`  ${statement.text}`)
    }
  }
}

// Store cursor for pagination
const nextCursor = results.cursor

cURL

curl --location --request POST 'https://api.alpha-sense.com/gql' \
  --header "x-api-key: $ALPHASENSE_API_KEY" \
  --header "clientid: $ALPHASENSE_CLIENT_ID" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "query SearchDocuments($filter: SearchFilter!, $limit: Int!, $sorting: SearchSorting!, $cursor: String) { search(filter: $filter, limit: $limit, sorting: $sorting, cursor: $cursor) { cursor totalCount documents { id title releasedAt snippets(limit: 20) { statements { text } } } } }",
    "variables": {
      "filter": {
        "keyword": {
          "query": "AI strategy"
        },
        "date": {
          "preset": "LAST_30_DAYS"
        }
      },
      "limit": 20,
      "sorting": {
        "field": "DATE",
        "direction": "DESC"
      }
    }
  }'

Response Handling

A successful response returns a JSON object with the following structure:

{
  "data": {
    "search": {
      "cursor": "eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0=",
      "totalCount": 342,
      "documents": [
        {
          "id": "doc-abc-123",
          "title": "Q4 Earnings Call Transcript - AI Strategy Overview",
          "releasedAt": "2025-11-15T14:30:00Z",
          "snippets": [
            {
              "statements": [
                {
                  "text": "Our AI strategy focuses on three core pillars: automation, intelligence augmentation, and predictive analytics..."
                }
              ]
            }
          ]
        }
      ]
    }
  }
}

Check for errors in the response before processing results:

Python

data = response.json()

if "errors" in data:
    for error in data["errors"]:
        print(f"Error: {error['message']}")
else:
    results = data["data"]["search"]
    print(f"Found {results['totalCount']} documents")

JavaScript

const data = await response.json()

if (data.errors) {
  for (const error of data.errors) {
    console.error(`Error: ${error.message}`)
  }
} else {
  const results = data.data.search
  console.log(`Found ${results.totalCount} documents`)
}

Pagination

The Document Search API uses cursor-based pagination. Each response includes a cursor field that points to the next page of results. To retrieve subsequent pages, pass the cursor value from the previous response as the cursor variable in your next request.

Python

cursor = None
all_documents = []

while True:
    variables = {
        "filter": {
            "keyword": {"query": "AI strategy"},
            "date": {"preset": "LAST_30_DAYS"}
        },
        "limit": 20,
        "sorting": {"field": "DATE", "direction": "DESC"},
        "cursor": cursor,
    }

    response = requests.post(url, headers=headers, json={"query": query, "variables": variables})
    data = response.json()
    results = data["data"]["search"]

    all_documents.extend(results["documents"])
    cursor = results["cursor"]

    if not cursor:
        break

print(f"Retrieved {len(all_documents)} of {results['totalCount']} total documents")

JavaScript

let cursor = null
const allDocuments = []

do {
  const variables = {
    filter: {
      keyword: {query: 'AI strategy'},
      date: {preset: 'LAST_YEAR'},
    },
    limit: 20,
    sorting: {field: 'DATE', direction: 'DESC'},
    cursor,
  }

  const response = await fetch(url, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      clientid: CLIENT_ID,
      Authorization: `Bearer ${ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({query, variables}),
  })

  const data = await response.json()
  const results = data.data.search

  allDocuments.push(...results.documents)
  cursor = results.cursor
} while (cursor)

console.log(`Retrieved ${allDocuments.length} total documents`)

When cursor is null or not present in the response, you have reached the last page of results.

tip

Uses the same GraphQL schema as Search API. Explore the full schema in the GraphQL Explorer.