> ## Documentation Index > Fetch the complete documentation index at: https://trakkr.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Get scores > Retrieve historical brand visibility and presence scores with optional breakdowns by AI model and/or prompt. **Important:** The date range (end_date - start_date) cannot exceed 90 days. ## OpenAPI ````yaml openapi.yaml get /get-scores openapi: 3.0.0 info: title: Trakkr API description: Monitor your brand visibility and presence across AI models and prompts version: 1.0.0 contact: name: Trakkr Support email: mack@trakkr.ai url: https://learn.trakkr.ai license: name: Proprietary url: https://trakkr.ai/ servers: - url: https://api.trakkr.ai description: Production server security: - bearerAuth: [] paths: /get-scores: get: summary: Get scores description: > Retrieve historical brand visibility and presence scores with optional breakdowns by AI model and/or prompt. **Important:** The date range (end_date - start_date) cannot exceed 90 days. operationId: getScores parameters: - name: brand in: query required: true schema: type: string pattern: ^[0-9a-fx]{32}$ minLength: 32 maxLength: 32 description: The brand ID (32-character hexadecimal string) example: 0000000000000x000000000000000000 - name: breakdown in: query required: false style: form explode: false schema: type: array items: type: string enum: - model - prompt minItems: 0 maxItems: 2 uniqueItems: true description: | Array of breakdown types. Valid values: - `[]` or omitted - No breakdown, returns only time series data - `["model"]` - Break down by AI model - `["prompt"]` - Break down by prompt - `["model", "prompt"]` - Break down by both examples: no_breakdown: value: [] summary: No breakdown - time series only model_only: value: - model summary: Model breakdown only prompt_only: value: - prompt summary: Prompt breakdown only both: value: - model - prompt summary: Both model and prompt breakdown - name: start_date in: query required: false schema: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: > Start date in YYYY-MM-DD format. If not provided, defaults to 28 days before end_date. The total date range cannot exceed 90 days. example: '2025-01-01' - name: end_date in: query required: false schema: type: string format: date pattern: ^\d{4}-\d{2}-\d{2}$ description: > End date in YYYY-MM-DD format. If not provided, defaults to the most recent report date for the brand. The total date range cannot exceed 90 days. example: '2025-01-31' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/ScoresResponse' examples: basic_response: $ref: '#/components/examples/BasicScoresResponse' model_breakdown_response: $ref: '#/components/examples/ModelBreakdownResponse' full_breakdown_response: $ref: '#/components/examples/FullBreakdownResponse' '400': description: Bad Request - Invalid parameters or date range exceeds 90 days content: application/json: schema: $ref: '#/components/schemas/Error' examples: date_range_too_large: value: error: Date range too large errors: - The total date range cannot exceed 90 days timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 invalid_parameter: value: error: INVALID_PARAMETER message: Invalid request parameters details: - field: brand message: Brand ID must be 32 characters timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ScoresResponse: type: object required: - brand_id - brand_name - start_date - end_date - breakdown - data properties: brand_id: type: string pattern: ^[0-9a-fx]{32}$ description: The brand ID that was queried example: 0000000000000x000000000000000000 brand_name: type: string description: The human-readable brand name example: Acme Corporation start_date: type: string format: date description: The start date used for the query example: '2025-01-01' end_date: type: string format: date description: The end date used for the query example: '2025-01-31' breakdown: type: array description: The breakdown types that were requested items: type: string enum: - model - prompt example: - model data: type: array description: Array of daily report data items: $ref: '#/components/schemas/DailyReport' errors: type: array nullable: true description: Array of non-critical error messages (null if no errors) items: type: string Error: type: object required: - error - timestamp properties: error: type: string description: Error code example: INVALID_PARAMETER message: type: string description: Human-readable error message example: The 'brand' parameter is required errors: type: array description: Array of error messages (alternative to details) items: type: string details: type: array items: type: object properties: field: type: string description: Field that caused the error message: type: string description: Specific error message for this field description: Detailed error information timestamp: type: string format: date-time description: When the error occurred example: '2025-01-15T12:30:00Z' request_id: type: string description: Unique request identifier for debugging example: req_1234567890 DailyReport: type: object required: - date - visibility - presence properties: date: type: string format: date description: The report date example: '2025-01-01' visibility: type: number format: float minimum: 0 maximum: 100 description: Brand visibility score (0.00 to 100.00) example: 85.5 presence: type: number format: float minimum: 0 maximum: 100 description: Brand presence score (0.00 to 100.00) example: 92.3 models: type: array description: Model breakdown data (present if "model" in breakdown) items: $ref: '#/components/schemas/ModelScore' prompts: type: array description: Prompt breakdown data (present if "prompt" in breakdown) items: $ref: '#/components/schemas/PromptScore' model_prompt_breakdown: type: array description: Combined model/prompt data (present if both in breakdown) items: $ref: '#/components/schemas/ModelPromptScore' ModelScore: type: object required: - model - visibility - presence properties: model: type: string description: The AI model name example: OpenAI visibility: type: number format: float minimum: 0 maximum: 100 description: Model-specific visibility score example: 88.2 presence: type: number format: float minimum: 0 maximum: 100 description: Model-specific presence score example: 94.1 PromptScore: type: object required: - id - visibility - presence - prompt properties: id: type: string description: Unique prompt identifier example: prompt_001 visibility: type: number format: float minimum: 0 maximum: 100 description: Prompt-specific visibility score example: 89.3 presence: type: number format: float minimum: 0 maximum: 100 description: Prompt-specific presence score example: 95.2 prompt: type: string description: The actual prompt text example: What are the best financial services companies? ModelPromptScore: type: object required: - model - prompt properties: model: type: string description: The AI model name example: OpenAI prompt: type: string description: The prompt text example: What are the best financial services companies? rank: type: number nullable: true minimum: 1 description: > Brand's average position in the response (null if not mentioned). For multiple results with the same model/prompt combination, this represents the average rank. example: 3 examples: BasicScoresResponse: summary: Basic response without breakdown value: brand_id: 0000000000000x000000000000000000 start_date: '2025-01-01' end_date: '2025-01-03' breakdown: [] data: - date: '2025-01-01' visibility: 85.5 presence: 92.3 - date: '2025-01-02' visibility: 87.2 presence: 91.8 - date: '2025-01-03' visibility: 86.9 presence: 93.1 errors: null ModelBreakdownResponse: summary: Response with model breakdown value: brand_id: 0000000000000x000000000000000000 start_date: '2025-01-01' end_date: '2025-01-02' breakdown: - model data: - date: '2025-01-01' visibility: 85.5 presence: 92.3 models: - model: OpenAI visibility: 88.2 presence: 94.1 - model: Anthropic visibility: 82.8 presence: 90.5 - date: '2025-01-02' visibility: 87.2 presence: 91.8 models: - model: OpenAI visibility: 89.1 presence: 93.5 - model: Anthropic visibility: 85.3 presence: 90.1 errors: null FullBreakdownResponse: summary: Response with both model and prompt breakdown value: brand_id: 0000000000000x000000000000000000 start_date: '2025-01-01' end_date: '2025-01-01' breakdown: - model - prompt data: - date: '2025-01-01' visibility: 85.5 presence: 92.3 models: - model: OpenAI visibility: 88.2 presence: 94.1 - model: Anthropic visibility: 82.8 presence: 90.5 prompts: - id: prompt_001 visibility: 89.3 presence: 95.2 prompt: What are the best financial services companies? - id: prompt_002 visibility: 81.7 presence: 89.4 prompt: Compare top investment platforms model_prompt_breakdown: - model: OpenAI prompt: What are the best financial services companies? rank: 3 - model: OpenAI prompt: Compare top investment platforms rank: null - model: Anthropic prompt: What are the best financial services companies? rank: 5 - model: Anthropic prompt: Compare top investment platforms rank: 2 errors: null responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' example: error: UNAUTHORIZED message: Missing API key errors: - >- API key must be provided in the Authorization header as 'Bearer ' timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 Forbidden: description: Forbidden - Access denied to this resource content: application/json: schema: $ref: '#/components/schemas/Error' example: error: FORBIDDEN message: Invalid API key errors: - No accounts found for this API key timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 NotFound: description: Not Found - Resource not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: NOT_FOUND message: Brand not found timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 TooManyRequests: description: Too Many Requests - Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/Error' example: error: RATE_LIMIT_EXCEEDED message: API rate limit exceeded. Please try again later. timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 headers: X-RateLimit-Limit: description: The rate limit for the endpoint schema: type: integer example: 100 X-RateLimit-Remaining: description: The number of requests remaining schema: type: integer example: 0 X-RateLimit-Reset: description: Unix timestamp when the rate limit resets schema: type: integer example: 1736947800 InternalServerError: description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' example: error: INTERNAL_ERROR message: An unexpected error occurred errors: - 'An unexpected error occurred: Database connection failed' timestamp: '2025-01-15T12:30:00Z' request_id: req_1234567890 securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > API key authentication. Include your API key in the Authorization header: `Authorization: Bearer YOUR_API_KEY` ````