llmrefs

---

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 👉 hello@llmrefs.com

• LLMrefs Website
• API Documentation
• OpenAPI Schema

---

Built by LLMrefs with ❤️, AI search analytics.