Skip to main content
POST
/
api
/
ad-spend
Get Ad Spend
curl --request POST \
  --url https://octanist.com/api/ad-spend \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "startDate": "2026-01-01",
  "endDate": "2026-03-01",
  "platform": "googleads",
  "groupBy": "date",
  "limit": 100,
  "page": 1
}
'
{
  "success": true,
  "data": [
    {
      "date": "2026-02-15",
      "campaignId": "123456789",
      "campaignName": "Spring Sale 2026",
      "adGroupId": "987654321",
      "adGroupName": "Brand Keywords",
      "platform": "googleads",
      "cost": 1500.5,
      "clicks": 2500,
      "impressions": 50000,
      "conversions": 125
    }
  ],
  "meta": {
    "pagination": {
      "limit": 50,
      "page": 1,
      "totalPages": 5,
      "total": 234,
      "hasMore": true
    },
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

​
Request Body

FieldTypeRequiredDefaultDescription
startDatestringYes-Start date (YYYY-MM-DD)
endDatestringYes-End date (YYYY-MM-DD)
platformstringNo-Filter by platform: googleads, meta, microsoftads
groupBystringNodateGroup by: date, campaign, adgroup, platform
limitnumberNo100Results per page (1-500)
pagenumberNo1Page number

​
Example Request

curl -X POST \
  -H "X-API-KEY: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-01-01",
    "endDate": "2026-03-01",
    "groupBy": "campaign",
    "limit": 10
  }' \
  "https://octanist.com/api/ad-spend"

​
Example Response (grouped by campaign)

{
  "success": true,
  "data": [
    {
      "campaignId": "123456789",
      "campaignName": "Spring Sale 2026",
      "platform": "googleads",
      "cost": 1500.5,
      "clicks": 2500,
      "impressions": 50000,
      "conversions": 125
    }
  ],
  "meta": {
    "pagination": {
      "limit": 10,
      "page": 1,
      "totalPages": 5,
      "total": 45,
      "hasMore": true
    },
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-10T12:00:00.000Z"
  }
}

​
Response Fields by groupBy

​
groupBy: date

{
  "date": "2026-02-15",
  "cost": 500.25,
  "clicks": 850,
  "impressions": 15000,
  "conversions": 42
}

​
groupBy: campaign

{
  "campaignId": "123456789",
  "campaignName": "Spring Sale 2026",
  "platform": "googleads",
  "cost": 1500.5,
  "clicks": 2500,
  "impressions": 50000,
  "conversions": 125
}

​
groupBy: adgroup

{
  "campaignId": "123456789",
  "campaignName": "Spring Sale 2026",
  "adGroupId": "987654321",
  "adGroupName": "Brand Keywords",
  "platform": "googleads",
  "cost": 750.25,
  "clicks": 1250,
  "impressions": 25000,
  "conversions": 62
}

​
groupBy: platform

{
  "platform": "googleads",
  "cost": 5000.0,
  "clicks": 10000,
  "impressions": 200000,
  "conversions": 500
}

​
Error Responses

StatusCodeDescription
400VALIDATION_ERRORInvalid request body or startDate > endDate
400INVALID_DATEInvalid date format (use YYYY-MM-DD)
401UNAUTHORIZEDMissing or invalid API key
500INTERNAL_ERRORServer error

Authorizations

​
X-API-KEY
string
header
required

API key for authentication

Body

application/json

Ad spend request parameters

​
startDate
string<date>
required

Start date (YYYY-MM-DD)

Example:

"2026-01-01"

​
endDate
string<date>
required

End date (YYYY-MM-DD)

Example:

"2026-03-01"

​
platform
enum<string>

Filter by platform

Available options:
googleads,
meta,
microsoftads
​
groupBy
enum<string>
default:date

Dimension to group results by

Available options:
date,
campaign,
adgroup,
platform
​
limit
integer
default:100

Results per page (1-500)

Required range: 1 <= x <= 500
​
page
integer
default:1

Page number

Required range: x >= 1

Response

Ad spend data retrieved successfully

​
success
boolean
Example:

true

​
data
object[]
​
meta
object