API Endpoints

Base URL

All API endpoints are relative to:

https://api.loamly.ai/v1

Visitors

List visitors

Retrieve a paginated list of visitors for your workspace.

GET /visitors

Query parameters

Example request

curl -X GET "https://api.loamly.ai/v1/visitors?source=chatgpt&limit=10" \
  -H "Authorization: Bearer loam_sk_live_xxxx"

Example response

{
  "data": [
    {
      "id": "vis_abc123",
      "first_seen": "2024-12-18T10:30:00Z",
      "last_seen": "2024-12-18T10:45:00Z",
      "source": "chatgpt",
      "intent": "solution_comparison",
      "pages_viewed": 5,
      "converted": true,
      "email": "user@example.com",
      "country": "US",
      "city": "San Francisco"
    }
  ],
  "meta": {
    "total": 1234,
    "limit": 10,
    "offset": 0
  }
}

Get visitor

Retrieve details for a specific visitor.

GET /visitors/:id

Get visitor timeline

Retrieve the complete activity timeline for a visitor.

GET /visitors/:id/timeline

Mentions

List mentions

Retrieve AI mentions of your brand.

GET /mentions

Query parameters

Example response

{
  "data": [
    {
      "id": "mnt_xyz789",
      "query": "best analytics tools for startups",
      "platform": "chatgpt",
      "response_snippet": "Loamly is an excellent choice for...",
      "position": 2,
      "sentiment": "positive",
      "competitors_mentioned": ["competitor1", "competitor2"],
      "created_at": "2024-12-18T09:00:00Z"
    }
  ],
  "meta": {
    "total": 567,
    "limit": 20,
    "offset": 0
  }
}

Analytics

Overview metrics

Get aggregate metrics for your workspace.

GET /analytics/overview

Query parameters

Example response

{
  "visitors": {
    "total": 12500,
    "change": 15.2
  },
  "pageviews": {
    "total": 45000,
    "change": 12.8
  },
  "conversions": {
    "total": 125,
    "rate": 1.0,
    "change": 22.5
  },
  "ai_traffic": {
    "total": 3200,
    "percentage": 25.6
  }
}

Traffic breakdown

Get visitor counts grouped by source.

GET /analytics/traffic

Conversion funnel

Get conversion metrics by stage.

GET /analytics/funnel

Intelligence

AI Positioning Score

Get your current AI Positioning Score and trend.

GET /intelligence/score

Example response

{
  "score": 72,
  "trend": {
    "direction": "up",
    "change": 5
  },
  "breakdown": {
    "visibility": 68,
    "sentiment": 85,
    "authority": 65,
    "coverage": 70
  },
  "updated_at": "2024-12-18T12:00:00Z"
}

Competitive ranking

Get your ranking against tracked competitors.

GET /intelligence/ranking

Error handling

The API uses standard HTTP status codes:

Error response format

{
  "error": {
    "code": "invalid_parameter",
    "message": "The 'source' parameter must be one of: chatgpt, perplexity, claude, gemini, organic, direct, paid, social, referral",
    "param": "source"
  }
}