List this tenant's promoted activities — server token only

GET

/v1/promoted

const url = 'http://localhost:3000/v1/promoted?limit=20';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'http://localhost:3000/v1/promoted?limit=20' \
  --header 'Authorization: Bearer <token>'

Newest first, retracted rows included (their deleted_at is set), with served_count for each. This is where delivery counts are read; there is no stats dashboard.

Authorizations

bearerAuth

Parameters

Query Parameters

limit

integer

default: 20 >= 1 <= 100

~~cursor~~

deprecated

string

Deprecated alias for next. next wins if both are sent.

next

string

Opaque paging token. Pass the next value from the previous page.

Responses

200

A page of promoted activities, newest first.

application/json

object

results

required

Array

next

required

Opaque cursor. Null when no further page.

string | null

results

required

Array<object>

The full row as returned to the tenant’s backend by GET /v1/promoted.

object

required

string format: uuid

actor

required

string

verb

required

string

object

required

string

custom

required

object

key

additional properties

any

audience

required

Null means every user. Otherwise feed refs; a caller matching ANY of them is eligible.

Array<string> | null

starts_at

required

string format: date-time

expires_at

required

string | null format: date-time

served_count

required

Feed opens that received this row — deliveries, not views. Repeat placement within one feed session does not increment it, and a viewport impression is not observable server-side; count those client-side via the react SDK callbacks.

integer

deleted_at

required

Set when retracted. Retracted rows stay listed here but are never served.

string | null format: date-time

created_at

required

string format: date-time

Example

{
  "results": [
    {
      "actor": "system:fcurban",
      "audience": [
        "city:belgrade"
      ]
    }
  ]
}

401

Invalid, expired, revoked, or absent token.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

403

User tokens cannot manage promoted activities — these routes are server token only.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

429

Rate limit exceeded.

application/json

object

error

required

object

code

required

string

Allowed values: VALIDATION_FAILED UNAUTHENTICATED FORBIDDEN NOT_FOUND CONFLICT RATE_LIMITED INTERNAL

message

required

string

requestId

required

string

fields

Present only for VALIDATION_FAILED.

Array<object>

object

path

string

message

string

Example

{
  "error": {
    "code": "VALIDATION_FAILED"
  }
}

Headers

Retry-After

integer