Placements

Use these endpoints to read the results of each placement (ad slot) and to create a placement without the dashboard.

GET `/publisher-dashboard/placements`

Returns the results for each placement, with a daily time series.

integer

default:"7"

The number of days to look back, from 1 to 365.

string

The start date (YYYY-MM-DD). Use it with end_date. A date range replaces days.

string

The end date (YYYY-MM-DD).

Request

curl "https://platform.trygravity.com/publisher-dashboard/placements?days=7" \
  -H "X-API-Key: YOUR_API_KEY"

Response

{
  "placements": [
    {
      "placement": "below_response",
      "impressions": 120000,
      "clicks": 600,
      "ctr": 0.005,
      "revenue": 600.00,
      "cpm": 5.00,
      "cpc": 1.00,
      "daily": [
        {
          "date": "2025-05-20",
          "impressions": 17000,
          "clicks": 85,
          "ctr": 0.005,
          "revenue": 85.00,
          "cpm": 5.00,
          "cpc": 1.00
        }
      ]
    }
  ],
  "period_days": 7
}

POST `/publisher-dashboard/placements`

Creates a placement (an ad slot). You do not need the dashboard. The slug in the response is the placement_id to send in ad requests. The new placement has the status active. Gravity refreshes the placement cache every 5 minutes. Until the refresh, ad requests get no ad for the new slot.

string

required

The display name, at most 100 characters. Gravity makes the slug from it ("Sidebar Slot" becomes Sidebar-Slot). The slug must be unique for your account.

string

default:"below_response"

One of above_response, below_response, inline_response, left_response, right_response, search_result, center_page, top_page, bottom_page, left_page, right_page.

string

default:"all"

One of all, desktop, mobile, tablet.

string

default:"any"

One of any, react, nextjs, vite, react-native, swift, vanilla, other.

string

The URL of the page or screen that has the slot.

string

Your notes.

object

Optional { "max_ad_text_chars": integer }. It sets the maximum length of the ad text for this slot. The minimum value is 120.

renderer_spec is the ad design that the slot uses. renderer_spec_source tells you where the design comes from: placement (the design of this slot), global (the default design of the platform), or null (the built-in layout of the SDK).

Status	Reason
`409`	A placement with the same slug is already in your account.
`422`	`name` is empty, has no letters or digits, or has more than 100 characters. Or an enum value is not valid, or `max_ad_text_chars` is less than 120.

Request

curl -X POST https://platform.trygravity.com/publisher-dashboard/placements \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sidebar Slot",
    "placement_type": "right_response",
    "device": "desktop",
    "page_url": "https://myplatform.com/chat"
  }'

Response 201 Created

{
  "id": "6f1c2d3e-...",
  "publisher_id": "abc-123",
  "name": "Sidebar Slot",
  "slug": "Sidebar-Slot",
  "placement_type": "right_response",
  "device": "desktop",
  "framework": "any",
  "page_url": "https://myplatform.com/chat",
  "description": null,
  "screenshot_url": null,
  "screenshot_region": null,
  "status": "active",
  "display_config": null,
  "renderer_spec": null,
  "renderer_spec_source": null,
  "created_at": "2026-09-10T20:45:00+00:00",
  "updated_at": "2026-09-10T20:45:00+00:00"
}

Get started

Advertisers

Publishers

API reference

Resources

GET `/publisher-dashboard/placements`

POST `/publisher-dashboard/placements`

​GET /publisher-dashboard/placements

​POST /publisher-dashboard/placements

GET `/publisher-dashboard/placements`

POST `/publisher-dashboard/placements`