Skip to main content

Exporting a ranking

Maps to: POST /v1/rankings/export

Produces a downloadable file from a ranking definition — the ranking equivalent of analysis export.

Request​

POST /v1/rankings/export

Unlike execute a ranking, the body's data is not the ranking definition itself — the definition is nested under data.ranking, alongside the export options:

{
  "meta": { "version": "v1" },
  "data": {
    "format": "excel",
    "ranking": {
      "title": "Buzz ranking",
      "entities": [
        { "brands_from_sector_id": 1, "region": "us", "only_active": true }
      ],
      "period": {
        "start_date": { "days": 30 },
        "end_date":   { "days": 1 }
      },
      "scoring": "total",
      "metrics_score_types": { "buzz": "net_score" },
      "filters": []
    }
  }
}

format is "excel" or "csv", and defaults to "excel" when omitted. Pasting an execute body into this endpoint fails — wrap the definition in ranking first.

Response​

A file download: the body is the file content, with a Content-Disposition header supplying the filename and a Content-Type for the format. Save the bytes using that filename.

Export vs the .csv execute suffix​

  • Export → a named file, best for sharing and spreadsheets.
  • .csv execute suffix → raw CSV inline, best for programmatic pulls.