Swaarm provides a Cost API that allows Singular to pull advertising cost data directly from your platform. Once set up, Singular queries Swaarm for cost, clicks, and conversion data per campaign - giving advertisers accurate ROI and ROAS metrics in their Singular dashboard.

How it works

Singular calls Swaarm's Cost API endpoint using a GET request. The API returns cost data per advertiser, broken down by campaign, with optional publisher-level granularity.

Endpoint

GET https://api.{yourdomain}.swaarm-clients.com/costapi/advertisers

Query parameters

Parameter	Format	Description
`start`	`YYYY-MM-DDTHH:MM:SS`	Start date in UTC
`end`	`YYYY-MM-DDTHH:MM:SS`	End date in UTC
`advertisers`	Comma-separated keys	Access keys for the advertisers to retrieve (e.g. `key1,key2,key3`)
`granularity`	`HOUR` / `DAY` / `WEEK` / `MONTH` / `YEAR`	Time granularity of the stats
`breakdown`	`publisher`	Optional — adds Publisher ID to the response

Example request

https://api.{yourdomain}.swaarm-clients.com/costapi/advertisers?advertisers=6f2187fe423c54e4f8ff9a200b910d82&start=2026-01-01T00:00:00&end=2026-01-07T00:00:00&granularity=day&breakdown=publisher

Data returned

The API returns a list of advertisers, each with their campaigns and stats:

Field	Description
`advertiser id`	Advertiser ID in Swaarm
`advertiser name`	Advertiser name in Swaarm
`campaigns`	List of campaigns that belong to the advertisers
`campaign id`	Offer ID in Swaarm
`campaign name`	Offer name
`campaign appId`	App ID of the offer
`campaign os`	Platform (iOS / Android)
`stats > clicks`	Number of clicks for this campaign
`stats > conversions`	Number of paid events for this campaign
`stats > cost`	Cost in cents (USD) - e.g. `40000` = $400.00
`stats > publisherId`	Publisher ID in Swaarm (only with `breakdown=publisher`)
`stats`	List of campaign stats according to the start and end date in the initial request

ℹ️ Cost is returned in cents in USD. Divide by 100 to get the dollar value.

Example response:

json

{
  "advertisers": [
    {
      "id": "4",
      "name": "Test Advertiser",
      "campaigns": [
        {
          "appId": "com.test.demo",
          "id": "10",
          "name": "Test Offer",
          "os": "Android",
          "stats": [
            {
              "clicks": 4,
              "conversions": 4,
              "cost": 40000,
              "publisherId": "6",
              "start": "2025-04-21T00:00:00",
              "end": "2025-04-22T00:00:00"
            }
          ]
        }
      ]
    }
  ]
}

Setting up the integration with Singular

To connect Singular to your Swaarm Cost API, share the following with the Singular team:

Your Cost API endpoint - https://api.{yourdomain}.swaarm-clients.com/costapi/advertisers
Advertiser access keys - one key per advertiser you want Singular to pull data for
Get it on Advertiser page here:

ℹ️ The advertiser access key is how Singular authenticates requests per advertiser. Each advertiser has their own key - you need to share the correct key for each advertiser the client wants to track in Singular.

⚠️ Keep advertiser access keys confidential - do not share them publicly or include them in shared documents without appropriate access controls.

Error responses

GET /costapi/advertisers returns errors as plain text - not JSON. Check the HTTP status code to determine how to handle the error.

400 Bad Request

The request was rejected before any data lookup. Fix the offending parameter and resend - do not retry the same request.

Body	What to fix
`Invalid start date. Format should be: 1776-07-04T00:00:00`	`start` must be ISO local datetime with no timezone suffix, interpreted as UTC
`Invalid end date. Format should be: 1776-07-04T00:00:00`	Same format as `start`
`Invalid time granularity. Accepted values are: YEAR / MONTH / WEEK / DAY / HOUR.`	Use one of the listed values (case-insensitive). Omit to default to `DAY`

500 Internal Server Error

A server-side failure. Treat as transient and retry with exponential backoff. If it persists, contact support with the request parameters and approximate timestamp.