llmrefs is maintained by LLMrefs - AI SEO brand visibility & LLM rank tracker.

✅ Open source AI search analytics & LLM visibility Javascript SDK

• Track your brand's visibility across AI search engines (LLMs)
• Monitor keyword rankings and share of voice
• Analyze AI-generated responses and brand mentions
• Get detailed analytics for AI SEO performance
• Full TypeScript support with detailed type definitions

Installation

npm install llmrefs

Quick Start

import { LLMrefs } from 'llmrefs';

// Initialize the client
const llmrefs = new LLMrefs({
  apiKey: 'your_api_key', // or set LLMREFS_API_KEY env variable
});

// List organizations
const organizations = await llmrefs.organizations.list();

// List projects for an organization
const projects = await llmrefs.projects.list({
  organizationId: 'org-123',
});

// List keywords for a project
const keywords = await llmrefs.keywords.list({
  projectId: 'proj-456',
  organizationId: 'org-123',
});

// Get detailed keyword analytics
const keywordData = await llmrefs.keywords.get({
  keywordId: 'kw-789',
  projectId: 'proj-456',
  organizationId: 'org-123',
});

API Reference

Authentication

Sign up for a free API key at 👉 llmrefs.com/signup.

You can provide your API key in two ways:

1. Pass it when initializing the client:

const llmrefs = new LLMrefs({ apiKey: 'your_api_key' });

2. Set it as an environment variable:

export LLMREFS_API_KEY=your_api_key

const llmrefs = new LLMrefs(); // Will use LLMREFS_API_KEY env variable

Listing Organizations

Get all organizations you have access to:

const organizations = await llmrefs.organizations.list();

console.log(organizations);
// => [
//   { id: 'org-1', name: 'My Organization' },
//   { id: 'org-2', name: 'Another Organization' },
//   ...
// ]

Listing Projects

Get all projects for a specific organization:

const projects = await llmrefs.projects.list({
  organizationId: 'org-123',
});

console.log(projects);
// => [
//   { id: 'proj-1', name: 'My Project', domain: 'example.com' },
//   { id: 'proj-2', name: 'Another Project', domain: 'test.com' },
//   ...
// ]

Listing Keywords

Get all active keywords for a project:

const keywords = await llmrefs.keywords.list({
  organizationId: 'org-123',
  projectId: 'proj-456',
});

console.log(keywords);
// => [
//   {
//     id: 'kw-1',
//     value: 'artificial intelligence',
//     location: 'US',
//     searchVolume: 10000
//   },
//   ...
// ]

Listing Search Engines

Get all available AI search engines (LLMs) tracked by LLMrefs:

const searchEngines = await llmrefs.keywords.searchEngines();

console.log(searchEngines);
// => [
//   { value: 'openai_chatgpt', name: 'OpenAI ChatGPT' },
//   { value: 'google_ai_mode', name: 'Google AI Mode' },
//   ...
// ]

Listing Locations

Get all available locations tracked by LLMrefs:

const locations = await llmrefs.keywords.locations();

console.log(locations);
// => [
//   { value: 'united_states', name: 'United States' },
//   { value: 'united_kingdom', name: 'United Kingdom' },
//   ...
// ]

Getting Keyword Analytics

Get detailed AI SEO analytics for a specific keyword:

const keywordData = await llmrefs.keywords.get({
  keywordId: 'kw-789',
  organizationId: 'org-123',
  projectId: 'proj-456',
  filters: {
    searchEngines: ['openai_chatgpt', 'google_ai_mode'], // Optional: filter by specific AI search engines
  },
});

console.log(keywordData);
// => {
//   id: 'kw-789',
//   value: 'artificial intelligence',
//   location: 'US',
//   searchVolume: 10000,
//   rankings: [
//     {
//       rank: 1,
//       brandId: 'brand-1',
//       shareOfVoice: '50%',
//       averagePosition: '1.5',
//       sources: ['source1', 'source2']
//     },
//     ...
//   ],
//   sources: [
//     {
//       source: 'source1',
//       mentionRate: '30%',
//       averagePosition: '2.0',
//       brandIds: ['brand-1']
//     },
//     ...
//   ],
//   responses: [
//     {
//       prompt: 'What is artificial intelligence?',
//       searchEngine: 'openai_chatgpt',
//       text: 'AI response text...',
//       brandsIds: ['brand-1'],
//       sources: ['source1']
//     },
//     ...
//   ],
//   brands: [
//     { id: 'brand-1', name: 'My Brand', domain: 'mybrand.com' },
//     ...
//   ]
// }

Features in Detail

AI Search Analytics

• Track your brand's visibility across multiple AI search engines (LLMs)
• Monitor keyword rankings and share of voice metrics
• Analyze how AI models respond to prompts surrounding your keywords topics
• View search volume for keywords across AI search engines
• Get insights into brand mentions and positioning

Keyword Tracking

• Monitor keyword performance across different AI platforms
• Track rankings, average positions, and share of voice
• Filter results by specific AI search engines
• Access historical and real-time analytics data

Error Handling

The SDK throws descriptive errors for invalid API keys, failed requests, and API errors:

try {
  const organizations = await llmrefs.organizations.list({});
} catch (error) {
  console.error('Error listing organizations:', error.message);
}

TypeScript Support

The SDK is written in TypeScript and provides comprehensive type definitions:

import {
  LLMrefs,
  LLMrefsOptions,
  ListOrganizationsOptions,
  ListProjectsOptions,
  ListKeywordsOptions,
  GetKeywordOptions,
} from 'llmrefs';

// All options are fully typed
const options: GetKeywordOptions = {
  keywordId: 'kw-789',
  projectId: 'proj-456',
  organizationId: 'org-123',
};

Types

LLMrefsOptions

| Property | Type | Description | Required | | -------- | -------- | -------------------- | ---------------------------- | | apiKey | string | Your LLMrefs API key | false (if set via env var) |

ListOrganizationsOptions

No properties required. Pass an empty object {}.

ListProjectsOptions

| Property | Type | Description | Required | | ---------------- | -------- | --------------- | -------- | | organizationId | string | Organization ID | true |

ListKeywordsOptions

| Property | Type | Description | Required | | ---------------- | -------- | --------------- | -------- | | organizationId | string | Organization ID | true | | projectId | string | Project ID | true |

GetKeywordOptions

| Property | Type | Description | Required | | ----------------------- | ---------- | --------------------------------- | -------- | | keywordId | string | Keyword ID | true | | organizationId | string | Organization ID | true | | projectId | string | Project ID | true | | filters | object | Optional filters | false | | filters.searchEngines | string[] | Filter by AI search engine values | false |

License

Distributed under the MIT License. See LICENSE for more information.

Links

If you need support please contact us at 👉 [email protected]

• LLMrefs Website
• API Documentation
• OpenAPI Schema

Built by LLMrefs with ❤️, AI search analytics.