> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trygravity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Placements

> Create placements and read the results of each placement.

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.

**days** `integer` (default: 7)

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

**start\_date** `string`

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

**end\_date** `string`

The end date (`YYYY-MM-DD`).

```bash Request theme={null}
curl "https://platform.trygravity.com/publisher-dashboard/placements?days=7" \
  -H "X-API-Key: YOUR_API_KEY"
```

```json Response theme={null}
{
  "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.

**name** `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.

**placement\_type** `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`.

**device** `string` (default: all)

One of `all`, `desktop`, `mobile`, `tablet`.

**framework** `string` (default: any)

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

**page\_url** `string`

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

**description** `string`

Your notes.

**display\_config** `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. |

```bash Request theme={null}
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"
  }'
```

```json Response 201 Created theme={null}
{
  "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"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.