Developer docs

How to use gist

Topic

Area of gist coverage to search, such as travel.

Query

The subject or market segment to explore within that area, such as solo backpacking travellers.

Trend

Patterns and themes gaining attention in social conversations related to your query.

Keywords

Related terms people use around a trend. The numerical metrics belong to these terms.

Start with Keywords to discover trends: emerging finds what is gaining attention, while prevalent finds what is prominent now. Use Answers when you need more context or want to ask your own question. Keywords and Answers work independently; an Answers request does not require a preceding Keywords request.

Quickstart

The base URL is https://gist-api.the-alt.co.

Create an API key in the dashboard. Send it as a bearer token in the Authorization header.

Keep your key in a server-side environment variable; do not include it in browser code. Set GIST_KEY before running the requests below. See Choose a topic for available topic names.

export GIST_KEY="your_api_key"

curl -X POST https://gist-api.the-alt.co/v1/keywords/travel \
  -H "Authorization: Bearer $GIST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"solo backpacking travellers"}'

{
  "signals": [{
    "label": "Autumn Golden Larch Hiking",
    "context": "Solo backpackers and hikers heading out during early October for peak fall foliage and larch season treks through mountain trails and national parks.",
    "keywords": ["golden larch"],
    "keywordStats": [{"phrase":"golden larch","shareOfVoice":2.2,"growth":28.1,"intent":null}]
  }]
}

Excerpt of the actual response: a trend, its context, and one related keyword with metrics. See the Keywords reference for the larger example with supporting posts and the full field descriptions.

Use gist in AI assistants (MCP)

gist is also a remote MCP server, so AI assistants such as Claude, ChatGPT, Cursor and VS Code can use Keywords and Answers directly, without writing code. Add this server URL to your assistant:

https://gist-api.the-alt.co/mcp

The first time your assistant uses gist, it opens a gist sign-in page. Enter your email, open the sign-in link we send you, then review and allow access. The assistant then runs queries as your account, with the same plan and units as the API: each uncached call costs 1 unit. It stays connected as long as you use it at least once every 90 days.

Both tools return the same results as their endpoints, including noSignal, knowledgeCutoff and usage, so the rest of this reference applies to them too.

Add gist to your assistant

• Claude (web and desktop): go to Customize → Connectors → Add → Add custom connector, and paste the server URL. On Team and Enterprise plans, an owner adds it under Organization settings → Connectors. See Claude’s guide.
• ChatGPT: turn on developer mode, then add a custom MCP connector with the server URL and OAuth authentication. See OpenAI’s guide for where these settings are.
• Claude Code, Cursor and VS Code: use the configuration below.

claude mcp add --transport http gist https://gist-api.the-alt.co/mcp
# then run /mcp in Claude Code and choose gist to sign in

Clients that can’t sign you in, and automated agents, can send an API key in the Authorization header instead, as in the last tab. Keep the key out of config files you share or commit.

Keywords discovers trends gaining attention or prominent now, with related keywords, metrics, supporting context and source posts. Its structured output helps tools decide what to surface, create, or explore.

See the Keywords guide for a worked skincare example and a content pipeline using this endpoint.

Each trend includes context explaining what people are discussing and how it relates to your query. This helps AI agents interpret the related keywords and decide what to create or explore.

Each trend in signals has a name (label), an explanation (context), related keywords, keyword-level metrics in keywordStats, and supporting posts.

mode: "emerging" finds trends gaining attention in the latest week of available data; it is the default. mode: "prevalent" finds trends prominent in that week. A trend's related keywords do not all need positive growth: mountains has negative growth in the prevalent example below.

curl -X POST https://gist-api.the-alt.co/v1/keywords/travel \
  -H "Authorization: Bearer $GIST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"solo backpacking travellers","format":"json","mode":"emerging"}'

curl -X POST https://gist-api.the-alt.co/v1/keywords/travel \
  -H "Authorization: Bearer $GIST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"solo backpacking travellers","format":"json","mode":"prevalent"}'

Answers explains what people are saying about a question, with supporting posts. Its output is prose for research or an agent’s context. Ask about a trend discovered through Keywords, or bring your own question.

Use the short summary or the fuller read as context in an AI tool or research workflow. annotations link passages in read to supporting posts.

Each annotation has start and end zero-based Unicode character offsets into read. In JavaScript, Array.from(read).slice(start, end).join('') gives you the passage that post supports: start is inclusive and end is exclusive. Apply offsets to the original text before formatting it. Multiple posts can support the same passage.

If there is not enough evidence to answer your question, the request succeeds with noSignal: true. Check notes for evidence gaps or limits, even when an answer is returned.

curl -X POST https://gist-api.the-alt.co/v1/search/travel \
  -H "Authorization: Bearer $GIST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"solo backpacking travellers"}'

Use this endpoint to find available topics. In the response’s topics array, topicName is the display name, topicId is the name to use in your request URL, and searchable: true identifies topics ready for Keywords and Answers. Use all to have gist pick the most relevant topics your key can access for the query.

curl https://gist-api.the-alt.co/v1/topics -H "Authorization: Bearer $GIST_KEY"

Request and response conventions

Both endpoints use a topic slug in the path to select one area of coverage. Use all to have gist pick the most relevant topics your key can access for the query. The response's topics array shows which were searched.

Use geo to filter by where authors or creators are based. For example, "geo": "UAE" restricts results to UAE-based creators. More specific locations, such as "Dubai", are supported on a best-effort basis using creators’ stated locations. To explore a place as a subject, include it in query.

knowledgeCutoff tells you how up to date the information behind the results is. For example, October 4 means the results draw on information through October 4.

An uncached successful request costs 1 unit. A cached response costs 0 units. A response with noSignal: true is still successful and costs 1 unit unless cached. Check usage.cached and usage.unitsRemaining for each response. Repeating a request does not guarantee a cache hit.

noSignal: true means there was not enough evidence to return supported results. Keywords returns an empty signals array; Answers uses notes to explain the evidence gap. An empty signals array alone does not mean no signal: Keywords also returns one for format: "text".

Handle a response

1. Check the HTTP status. For an error, follow the guidance below.
2. Check noSignal before displaying results; for Answers, also check notes.
3. Use the trends or answer, and retain supporting source links.
4. Keep knowledgeCutoff with the results and check the remaining units in usage.

Errors

Check the HTTP status first. Application errors use this JSON envelope:

{
  "error": {
    "code": "not_found",
    "message": "No current material for topic 'travel'."
  }
}

Authentication errors use a different shape. A missing or invalid key returns HTTP 401, for example:

{
  "statusCode": 401,
  "message": "Provide a valid API key or sign in.",
  "error": "Unauthorized"
}

An account setup failure can also return HTTP 403 with statusCode, message, and error fields.

For rate_limited or engine_unavailable, wait and retry, increasing the delay between attempts. For quota_exceeded, replenish your units before retrying. For 400, 401, or 403, correct the request, credentials, or access issue first.