{
  "info": {
    "name": "LLMPulse API v1",
    "_postman_id": "f52adfc8-6809-45c0-895b-dda717946249",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "description": "Postman collection to explore the LLMPulse API v1: dimensions and metrics."
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://api.llmpulse.ai/api/v1"
    },
    {
      "key": "project_id",
      "value": "4"
    },
    {
      "key": "competitors",
      "value": "1,19,20"
    },
    {
      "key": "page",
      "value": "1"
    },
    {
      "key": "per_page",
      "value": "20"
    },
    {
      "key": "range",
      "value": "30"
    },
    {
      "key": "metrics_all",
      "value": "mentions,citations,responses,visibility,citation_rate,avg_position,ai_visibility_score,sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative,net_sentiment"
    }
  ],
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "pm.test('Status is 200 or 304', function () {",
          "  pm.expect(pm.response.code === 200 || pm.response.code === 304).to.be.true;",
          "});"
        ]
      }
    }
  ],
  "item": [
    {
      "name": "Dimensions",
      "item": [
        {
          "name": "Projects (list all)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/projects",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "projects"
              ]
            }
          }
        },
        {
          "name": "Competitors",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/competitors?project_id={{project_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "competitors"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                }
              ]
            }
          }
        },
        {
          "name": "Collections (tags)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/collections?project_id={{project_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "collections"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                }
              ]
            }
          }
        },
        {
          "name": "Models",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/models?project_id={{project_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "models"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                }
              ]
            }
          }
        },
        {
          "name": "Locales",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/locales?project_id={{project_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "locales"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                }
              ]
            }
          }
        },
        {
          "name": "Prompts",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/prompts?project_id={{project_id}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "prompts"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                }
              ]
            }
          }
        },
        {
          "name": "Prompt Executions",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/prompt_executions?project_id={{project_id}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "prompt_executions"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Sources",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/sources?project_id={{project_id}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "sources"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Mentions",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/mentions?project_id={{project_id}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "mentions"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Citations",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/citations?project_id={{project_id}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "citations"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Competitor Mentions",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/competitor_mentions?project_id={{project_id}}&competitors={{competitors}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "competitor_mentions"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Competitor Citations",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/competitor_citations?project_id={{project_id}}&competitors={{competitors}}&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "competitor_citations"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Sentiments (buckets & colors)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/sentiments?project_id={{project_id}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "dimensions",
                "sentiments"
              ],
              "query": [
                { "key": "project_id", "value": "{{project_id}}" }
              ]
            }
          }
        },
        {
          "name": "Tags (alias of Collections)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/dimensions/tags?project_id={{project_id}}",
              "host": ["{{base_url}}"],
              "path": ["dimensions","tags"],
              "query": [
                { "key": "project_id", "value": "{{project_id}}" }
              ]
            }
          }
        }
      ]
    },
    {
      "name": "Metrics",
      "item": [
        {
          "name": "Timeseries \u2014 daily, last {{range}} days",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}&metrics={{metrics_all}}&granularity=day&range={{range}}&competitors={{competitors}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "timeseries"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "metrics",
                  "value": "{{metrics_all}}"
                },
                {
                  "key": "granularity",
                  "value": "day"
                },
                {
                  "key": "range",
                  "value": "{{range}}"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Timeseries \u2014 weekly window (Overview semantics)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}&metrics=mentions,citations,visibility,avg_position&granularity=week&from=2025-01-01&to=2025-01-31&competitors={{competitors}}&model=gpt-4o",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "timeseries"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "metrics",
                  "value": "mentions,citations,visibility,avg_position"
                },
                {
                  "key": "granularity",
                  "value": "week"
                },
                {
                  "key": "from",
                  "value": "2025-01-01"
                },
                {
                  "key": "to",
                  "value": "2025-01-31"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "model",
                  "value": "gpt-4o"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            },
            "description": "Server calculates week totals with sticky carry, visibility as ratio of weekly sums, and avg_position with propagation."
          }
        },
        {
          "name": "Timeseries \u2014 competitor-only (include_project=false)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}&metrics=visibility&granularity=month&range=90&competitors={{competitors}}&include_project=false",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "timeseries"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "metrics",
                  "value": "visibility"
                },
                {
                  "key": "granularity",
                  "value": "month"
                },
                {
                  "key": "range",
                  "value": "90"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "include_project",
                  "value": "false"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Summary \u2014 monthly, last 365 days",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/summary?project_id={{project_id}}&metrics=mentions,avg_position&granularity=month&range=365",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "summary"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "metrics",
                  "value": "mentions,avg_position"
                },
                {
                  "key": "granularity",
                  "value": "month"
                },
                {
                  "key": "range",
                  "value": "365"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "SOV \u2014 last 90 days",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/sov?project_id={{project_id}}&range=90&competitors={{competitors}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "sov"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "range",
                  "value": "90"
                },
                {
                  "key": "competitors",
                  "value": "{{competitors}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            },
            "description": "Response now includes breakdown (top 4 + Others) and others list, mirroring Overview."
          }
        },
        {
          "name": "Top sources \u2014 sort by avg_visibility",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/top_sources?project_id={{project_id}}&range=30&sort=avg_visibility&page={{page}}&per_page={{per_page}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "top_sources"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "range",
                  "value": "30"
                },
                {
                  "key": "sort",
                  "value": "avg_visibility"
                },
                {
                  "key": "page",
                  "value": "{{page}}"
                },
                {
                  "key": "per_page",
                  "value": "{{per_page}}"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            }
          }
        },
        {
          "name": "Top sources \u2014 filter by domain (query)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/top_sources?project_id={{project_id}}&range=30&query=github",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "top_sources"
              ],
              "query": [
                {
                  "key": "project_id",
                  "value": "{{project_id}}"
                },
                {
                  "key": "range",
                  "value": "30"
                },
                {
                  "key": "query",
                  "value": "github"
                },
                {
                  "key": "prompt",
                  "value": "",
                  "description": "Filter by prompt ID",
                  "disabled": true
                }
              ]
            },
            "description": "Uses `query` param to filter domains (case-insensitive LIKE)."
          }
        },
        {
          "name": "Timeseries — Sentiment (daily, last {{range}} days)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}&metrics=sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative&granularity=day&range={{range}}&competitors={{competitors}}",
              "host": [
                "{{base_url}}"
              ],
              "path": [
                "metrics",
                "timeseries"
              ],
              "query": [
                { "key": "project_id",   "value": "{{project_id}}" },
                { "key": "metrics",      "value": "sentiment_very_positive,sentiment_positive,sentiment_neutral,sentiment_negative,sentiment_very_negative" },
                { "key": "granularity",  "value": "day" },
                { "key": "range",        "value": "{{range}}" },
                { "key": "competitors",  "value": "{{competitors}}" },
                { "key": "prompt", "value": "", "description": "Filter by prompt ID", "disabled": true }
              ]
            }
          },
          "description": "Returns sentiment buckets (% per day) for project + competitors."
        },
        {
          "name": "Timeseries — Net Sentiment (daily, last {{range}} days)",
          "request": {
            "method": "GET",
            "url": {
              "raw": "{{base_url}}/metrics/timeseries?project_id={{project_id}}&metrics=net_sentiment&granularity=day&range={{range}}&competitors={{competitors}}",
              "host": ["{{base_url}}"],
              "path": ["metrics","timeseries"],
              "query": [
                { "key": "project_id",  "value": "{{project_id}}" },
                { "key": "metrics",     "value": "net_sentiment" },
                { "key": "granularity", "value": "day" },
                { "key": "range",       "value": "{{range}}" },
                { "key": "competitors", "value": "{{competitors}}" },
                { "key": "prompt", "value": "", "description": "Filter by prompt ID", "disabled": true }
              ]
            }
          }
        }

      ]
    }
  ]
}