Skip to content
Listener.comDevelopers

Reports

Shared reports, report templates and report automations.

List shared reports

GET/v1/reports
reports:read

Shared reports, newest first, with headline reach numbers, element ids, scope and share URLs. search matches title, template id or network name.

SDKlistener.reports.list()client.reports.list()

Query parameters

  • searchstringnullable
    Case-insensitive text filter.
  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Publish a shared report

POST/v1/reports
reports:writeNeeds confirm=trueSupports dry_run

Publish a shared report with a frozen analytics snapshot and return its id and public URL. Needs "confirm": true because creating it publishes it: the page at urls.public is public and immutable (only DELETE /v1/reports/{report_id} changes it).

template_id is a built-in (network-overview, executive-summary, audio-template, social-reach, short-form, youtube-focused, cluster-overview, <platform>-focused …) or a custom id from GET /v1/report-templates; add_element_ids / remove_element_ids adjust its elements. time_range is 7d, 30d or 90d; on 90 days reach totals, trends and growth come from stored history while per-platform likes, comments and posts cover the last 30 days (noted in warnings). A dry run summarises the snapshot.

  • Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.
  • Requires "confirm": true; without it the API answers 409 confirmation_required with the exact preview.

SDKlistener.reports.create()client.reports.create()

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • titlestringrequired
    Title.
  • template_idstringrequired
  • time_rangestring
    7d | 14d | 30d | 90d | 180d | 365d | all, or a quarter like 2026-Q2. Windows are UTC days anchored to today.
    One of7d30d90d

    Default "30d"

  • add_element_idsarray of stringsnullable
  • remove_element_idsarray of stringsnullable
  • comparison_modestring
    previous_period or none.
    One ofprevious_periodnone

    Default "previous_period"

  • show_idsarray of stringsnullable
    Limit to these show ids (default: every show in the workspace).
  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

  • confirmboolean
    Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.

    Default false

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error

Retrieve a report

GET/v1/reports/{report_id}
reports:read

One shared report: metadata, scope, headline numbers, every element (KPIs, charts, tables, text) and, with include_data=true, the stored snapshot the public page renders. The snapshot is what was computed when the report was published; arrays over 200 items are truncated (data_truncated).

SDKlistener.reports.retrieve()client.reports.retrieve()

Path parameters

  • report_idstringrequired
    Shared report id (see GET /v1/reports).

Query parameters

  • include_databoolean

    Default true

Returns

200

OK

  • idstringrequired
  • titlestringrequired
  • headlineobjectrequired
    Show child attributesHide child attributes
  • urlsobjectrequired
    Show child attributesHide child attributes
  • computed_atstringrequired
  • cache_age_secondsnumberrequired
  • objectstringrequired
  • network_namestringnullable
  • time_rangestringnullable
  • comparison_modestringnullable
  • created_atstringnullable
  • updated_atstringnullable
  • created_bystringnullable
  • created_viastringnullable
  • is_automatedboolean

    Default false

  • is_testboolean

    Default false

  • template_idstringnullable
  • element_countinteger

    Default 0

  • element_idsarray of strings
  • element_metricsarray of strings
  • element_typesmap of integer
  • report_scopeobjectnullable
    Show child attributesHide child attributes
  • has_databoolean

    Default false

  • elementsarray of objects
    Show child attributesHide child attributes
  • dataobjectnullable
    The stored data snapshot (arrays truncated to 200 items when data_truncated).
  • data_keysarray of strings
  • data_truncatedboolean

    Default false

  • notestringnullable

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Delete a shared report

DELETE/v1/reports/{report_id}
reports:writeSome changes need confirmSupports dry_run

Permanently delete a shared report so its public page stops resolving, and list report automations whose last report still points at it (left as is, listed in warnings).

  • Send ?dry_run=true to get {"object": "dry_run", "would_write": …} without writing anything.
  • Requires ?confirm=true; without it the API answers 409 confirmation_required with the exact preview.

SDKlistener.reports.delete()client.reports.delete()

Path parameters

  • report_idstringrequired
    Shared report id (see GET /v1/reports).

Query parameters

  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

  • confirmboolean
    Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.

    Default false

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error

List report templates

GET/v1/report-templates
reports:read

Report templates: the built-in ones plus the workspace's custom templates, with their element ids. Use a template's id as template_id in POST /v1/reports.

SDKlistener.reportTemplates.list()client.report_templates.list()

Query parameters

  • searchstringnullable
    Case-insensitive text filter.
  • limitinteger1 to 100
    Page size, 1–100 (default 25).

    Default 25

  • cursorstring
    Opaque cursor from the previous page's next_cursor.

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Save a report template

POST/v1/report-templates
reports:writeSupports dry_run

Save a custom report template from a list of element ids (see GET /v1/report-templates for the elements the built-ins use). Nothing is published; use the returned id as template_id in POST /v1/reports.

  • Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.

SDKlistener.reportTemplates.create()client.report_templates.create()

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • namestringrequired
    Name.
  • element_idsarray of stringsrequired
  • descriptionstring
    Free-text description.

    Default ""

  • comparison_modestring
    previous_period or none.
    One ofprevious_periodnone

    Default "previous_period"

  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error

List report automations

GET/v1/report-automations
reports:read

Scheduled report automations: template, frequency, time range, shows, delivery (email masked, Slack configured or not, never the webhook), enabled flag, last and next run, last report URLs and delivery guardrails.

SDKlistener.reportAutomations.list()client.report_automations.list()

Returns

200

OK

  • objectstringrequired
  • urlstringrequired
  • dataarray of objectsrequired
    Show child attributesHide child attributes
  • has_morebooleanrequired
  • next_cursorstringrequirednullable
    Pass as cursor to get the next page; null on the last page.
  • metaobjectrequired
    The result's non-list fields (window, coverage, freshness, totals, note …).
    Show child attributesHide child attributes

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found429rate_limited500internal_error

Disable a report automation

POST/v1/report-automations/{automation_id}/disable
reports:writeSupports dry_run

Disable a scheduled report automation so it stops emailing or posting reports. Creating, enabling and deleting automations send outbound email and are app-only.

  • Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.

SDKlistener.reportAutomations.disable()client.report_automations.disable()

Path parameters

  • automation_idstringrequired
    Report automation id (see GET /v1/report-automations).

Headers

  • Idempotency-Keystringmax 255 chars
    Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json
  • dry_runboolean
    true returns exactly what would be written without writing anything (the API's test mode).

    Default false

Returns

200

OK

One of:

WriteResult
DryRun

Errors

400parameter_invalid401credential_invalid403scope_missing404resource_not_found409confirmation_required413body_too_large429rate_limited500internal_error