List promotions

List this rooftop's promotions, optionally filtered by status, type or name.

Each item has the same fields as Create a promotion returns. Performance numbers are only on Retrieve a promotion.

GEThttps://api.spyne.ai/api/pv1/promotions

AuthBearer tokenRate limit120 reads / min per rooftop

Before you call it

Counts toward the 120 reads a minute per rooftop.

Query parameters

Optionalcan be left out

Parameter	Type	Required	Description
`status`	string	Optional	`draft`, `scheduled`, `active`, `paused` or `completed`. Not case-sensitive.
`promotionType`	string	Optional	`custom` (hand-picked) or `dynamic` (filter-based). Lowercase only.
`search`	string	Optional	Part of the promotion name.
`page`	integer	Optional	Page number, starting at 1. Default: `1`.
`perPage`	integer	Optional	Promotions per page, 1 to 100. Default: `20`.

Sample request

curl --request GET \
  --url 'https://api.spyne.ai/api/pv1/promotions?status=active' \
  --header 'Authorization: Bearer YOUR_API_KEY'

import requests

url = "https://api.spyne.ai/api/pv1/promotions"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
params = {"status": "active"}

response = requests.get(url, headers=headers, params=params)
print(response.status_code, response.json())

const response = await fetch("https://api.spyne.ai/api/pv1/promotions?status=active", {
  method: "GET",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
  },
});
console.log(response.status, await response.json());

Sample response

{
  "success": true,
  "statusCode": 200,
  "data": {
    "total": 1,
    "page": 1,
    "perPage": 20,
    "promotions": [
      {
        "id": 351,
        "name": "Fall Clearance",
        "promotionType": "custom",
        "status": "active",
        "assets": [{ "assetId": "1584", "position": "all_images" }],
        "schedule": { "startDate": "2026-10-01T09:59:00Z", "neverEnds": true },
        "priority": 1000,
        "vehicleCount": 2
      }
    ]
  }
}

Response parameters (200)

Parameter	Type	Description
`data.total`	integer	Promotions that match, across all pages.
`data.page`	integer	The page returned.
`data.perPage`	integer	Promotions per page.
`data.promotions[]`	array	The promotions on this page. Each has the fields described in Create a promotion.

Errors

Status	Code	When it happens
`400`	`INVALID_REQUEST`	A query parameter is invalid. `details.errors` lists every problem.
`400`	`VALIDATION_FAILED`	Spyne refused the request; `details` explains why.
`400`	`TEAM_NOT_RESOLVED`	The API key isn't linked to a rooftop.
`401`	`UNAUTHORIZED`	The API key is missing or wrong.
`429`	`RATE_LIMITED`	More than 120 reads this minute. Wait the seconds in `Retry-After`.
`502` / `503`	`SERVICE_UNAVAILABLE`	A Spyne service is briefly unavailable. Retry shortly.

What happens next

Take an id and retrieve the promotion to see its performance.