Document Search API

The Document Search API is a companion utility to the Agent API. When an agent returns a document reference, use this API to look up document-level metadata for that reference — for example, the associated company and its ticker, the release date, and the page count.

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
      pageCount
      companies {
        name
        primaryTickerCode
      }
    }
  }
}

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

ACCESS_TOKEN = os.environ["ALPHASENSE_ACCESS_TOKEN"]  # see Authentication guide

headers = {
    "x-api-key": os.environ["ALPHASENSE_API_KEY"],
    "clientid": os.environ["ALPHASENSE_CLIENT_ID"],
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
}

query = """
query SearchDocuments($filter: SearchFilter!, $limit: Int!, $sorting: SearchSorting!) {
  search(filter: $filter, limit: $limit, sorting: $sorting) {
    cursor
    totalCount
    documents {
      id
      title
      releasedAt
      pageCount
      companies { name primaryTickerCode }
    }
  }
}
"""

variables = {
    "filter": {"companies": {"ids": ["AAPL"]}},
    "limit": 20,
    "sorting": {"field": "DATE", "direction": "DESC"},
}

response = requests.post(
    "https://api.alpha-sense.com/gql",
    headers=headers,
    json={"query": query, "variables": variables},
)
print(response.json())

JavaScript

const ACCESS_TOKEN = process.env.ALPHASENSE_ACCESS_TOKEN // see Authentication guide

const query = `
query SearchDocuments($filter: SearchFilter!, $limit: Int!, $sorting: SearchSorting!) {
  search(filter: $filter, limit: $limit, sorting: $sorting) {
    cursor
    totalCount
    documents {
      id
      title
      releasedAt
      pageCount
      companies { name primaryTickerCode }
    }
  }
}
`

const variables = {
  filter: {companies: {ids: ['AAPL']}},
  limit: 20,
  sorting: {field: 'DATE', direction: 'DESC'},
}

const response = await fetch('https://api.alpha-sense.com/gql', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.ALPHASENSE_API_KEY,
    clientid: process.env.ALPHASENSE_CLIENT_ID,
    Authorization: `Bearer ${ACCESS_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({query, variables}),
})

console.log(await response.json())

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!) { search(filter: $filter, limit: $limit, sorting: $sorting) { cursor totalCount documents { releasedAt pageCount companies { name primaryTickerCode } } } }",
    "variables": {
      "filter": { "companies": { "ids": ["AAPL"] } },
      "limit": 20,
      "sorting": { "field": "DATE", "direction": "DESC" }
    }
  }'

Example Response

{
  "data": {
    "search": {
      "cursor": "eyJsYXN0SWQiOiIxMjM0NTY3ODkwIn0=",
      "totalCount": 342,
      "documents": [
        {
          "releasedAt": 1731680400000,
          "pageCount": 24,
          "companies": [{"name": "Apple Inc.", "primaryTickerCode": "AAPL"}]
        }
      ]
    }
  }
}

Pagination

Responses are paginated with a cursor. To fetch the next page, pass the previous response's cursor value back as the cursor variable. When cursor is null, you've reached the last page.

tip

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