Data Endpoints

Use the data endpoints to read retained AIBeam aggregates for a project. These endpoints return selected-analysis data gathered from ChatGPT, Perplexity, Claude, and Gemini.

All examples below use the current v1 success envelope: successful responses return data directly, without a success: true wrapper. Error responses return success: false with an error object.

Authentication

Authorization: Bearer YOUR_API_KEY

API access is available on Professional and Agency plans.

Visibility

Visibility is the percentage of accepted response runs in the selected period where the target brand is present, shown on a 0-100 scale. It is not weighted by ranking position or market-leader share.

Endpoint

GET /api/v1/projects/:projectId/visibility

Parameters

Date windows are capped at 90 days.

Response

{
  "data": {
    "project_id": "789a1234-b56c-78d9-e012-f34567890123",
    "window": {
      "from": "2026-02-08",
      "to": "2026-03-10"
    },
    "by_platform": {
      "chatgpt": {
        "response_count": 40,
        "brand_mention_count": 31,
        "visibility_score": 78
      },
      "perplexity": {
        "response_count": 42,
        "brand_mention_count": 34,
        "visibility_score": 81
      },
      "claude": {
        "response_count": 39,
        "brand_mention_count": 24,
        "visibility_score": 62
      },
      "gemini": {
        "response_count": 41,
        "brand_mention_count": 30,
        "visibility_score": 73
      }
    },
    "score": 73,
    "trend": [
      {
        "date": "2026-03-08",
        "score": 71,
        "responses": 16
      },
      {
        "date": "2026-03-09",
        "score": 75,
        "responses": 16
      }
    ]
  }
}

Mention Trends

Mention trends return aggregate competitor/brand mention buckets from the selected analysis version. This endpoint does not return individual response excerpts.

Endpoint

GET /api/v1/projects/:projectId/mentions

Parameters

Response

{
  "data": {
    "mentions": [
      {
        "competitor_candidate_id": "123e4567-e89b-12d3-a456-426614174000",
        "competitor_id": "223e4567-e89b-12d3-a456-426614174000",
        "bucket_date": "2026-03-09",
        "mention_count": 14,
        "response_count": 20,
        "provider": "chatgpt"
      }
    ]
  },
  "pagination": {
    "limit": 50,
    "offset": 0,
    "has_more": false
  },
  "rate_limit": {
    "limit": 60,
    "remaining": 42,
    "reset": 1783587600
  }
}

Citations

Citations return aggregated cited domains with top URLs for each domain in the current page.

Endpoint

GET /api/v1/projects/:projectId/citations

Parameters

Response

{
  "data": [
    {
      "domain": "acme.example",
      "citation_count": 42,
      "response_count": 18,
      "first_seen": "2026-03-01T10:30:00Z",
      "last_seen": "2026-03-09T14:22:33Z",
      "top_urls": [
        {
          "url": "https://acme.example/features",
          "count": 16
        },
        {
          "url": "https://acme.example/pricing",
          "count": 8
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "cursor": null
  }
}

Sentiment

Sentiment returns selected-analysis sentiment counts for the project.

Endpoint

GET /api/v1/projects/:projectId/sentiment

Parameters

Response

{
  "data": {
    "sentiment": {
      "positive": 24,
      "neutral": 18,
      "negative": 3,
      "mixed": 2,
      "total": 47
    }
  },
  "rate_limit": {
    "limit": 60,
    "remaining": 41,
    "reset": 1783587600
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Date range must be 0-90 days"
  }
}

Common error codes are UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_ERROR, RATE_LIMIT_EXCEEDED, and INTERNAL_ERROR.

Rate Limiting

Rate limit status is included in headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1783587600

When rate limited, the API returns HTTP 429 with a RATE_LIMIT_EXCEEDED error and a Retry-After header when available.