> ## Documentation Index > Fetch the complete documentation index at: https://octanist.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Ad Spend > Retrieve ad spend data grouped by various dimensions ## Request Body | Field | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------- | | `startDate` | string | Yes | - | Start date (YYYY-MM-DD) | | `endDate` | string | Yes | - | End date (YYYY-MM-DD) | | `platform` | string | No | - | Filter by platform: `googleads`, `meta`, `microsoftads` | | `groupBy` | string | No | `date` | Group by: `date`, `campaign`, `adgroup`, `platform` | | `limit` | number | No | 100 | Results per page (1-500) | | `page` | number | No | 1 | Page number | ## Example Request ```bash theme={null} 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) ```json theme={null} { "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 ```json theme={null} { "date": "2026-02-15", "cost": 500.25, "clicks": 850, "impressions": 15000, "conversions": 42 } ``` ### groupBy: campaign ```json theme={null} { "campaignId": "123456789", "campaignName": "Spring Sale 2026", "platform": "googleads", "cost": 1500.5, "clicks": 2500, "impressions": 50000, "conversions": 125 } ``` ### groupBy: adgroup ```json theme={null} { "campaignId": "123456789", "campaignName": "Spring Sale 2026", "adGroupId": "987654321", "adGroupName": "Brand Keywords", "platform": "googleads", "cost": 750.25, "clicks": 1250, "impressions": 25000, "conversions": 62 } ``` ### groupBy: platform ```json theme={null} { "platform": "googleads", "cost": 5000.0, "clicks": 10000, "impressions": 200000, "conversions": 500 } ``` ## Error Responses | Status | Code | Description | | ------ | ------------------ | ------------------------------------------- | | 400 | `VALIDATION_ERROR` | Invalid request body or startDate > endDate | | 400 | `INVALID_DATE` | Invalid date format (use YYYY-MM-DD) | | 401 | `UNAUTHORIZED` | Missing or invalid API key | | 500 | `INTERNAL_ERROR` | Server error | ## OpenAPI ````yaml POST /api/ad-spend openapi: 3.0.1 info: title: Octanist API description: >- The Octanist API allows you to manage leads, retrieve statistics, and access ad spend data. version: 2.2.0 contact: name: Octanist Support url: https://octanist.com/docs servers: - url: https://octanist.com description: Production server security: - apiKeyAuth: [] paths: /api/ad-spend: post: tags: - Analytics summary: Get Ad Spend description: Retrieve ad spend data grouped by various dimensions. requestBody: description: Ad spend request parameters required: true content: application/json: schema: $ref: '#/components/schemas/AdSpendRequest' responses: '200': description: Ad spend data retrieved successfully content: application/json: schema: type: object properties: success: type: boolean example: true data: type: array items: $ref: '#/components/schemas/AdSpendEntry' meta: $ref: '#/components/schemas/PaginatedMeta' '400': description: Invalid request body, startDate > endDate, or invalid date format content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: AdSpendRequest: type: object required: - startDate - endDate properties: startDate: type: string format: date description: Start date (YYYY-MM-DD) example: '2026-01-01' endDate: type: string format: date description: End date (YYYY-MM-DD) example: '2026-03-01' platform: type: string enum: - googleads - meta - microsoftads description: Filter by platform groupBy: type: string enum: - date - campaign - adgroup - platform default: date description: Dimension to group results by limit: type: integer minimum: 1 maximum: 500 default: 100 description: Results per page (1-500) page: type: integer minimum: 1 default: 1 description: Page number AdSpendEntry: type: object description: Ad spend data entry. Fields vary based on the `groupBy` parameter. properties: date: type: string format: date description: Date (when groupBy is `date`) example: '2026-02-15' campaignId: type: string description: Campaign ID (when groupBy is `campaign` or `adgroup`) example: '123456789' campaignName: type: string description: Campaign name (when groupBy is `campaign` or `adgroup`) example: Spring Sale 2026 adGroupId: type: string description: Ad group ID (when groupBy is `adgroup`) example: '987654321' adGroupName: type: string description: Ad group name (when groupBy is `adgroup`) example: Brand Keywords platform: type: string enum: - googleads - meta - microsoftads description: Platform (when groupBy is `campaign`, `adgroup`, or `platform`) example: googleads cost: type: number description: Total cost example: 1500.5 clicks: type: integer description: Total clicks example: 2500 impressions: type: integer description: Total impressions example: 50000 conversions: type: integer description: Total conversions example: 125 PaginatedMeta: type: object properties: pagination: type: object properties: limit: type: integer example: 50 page: type: integer example: 1 totalPages: type: integer example: 5 total: type: integer example: 234 hasMore: type: boolean example: true requestId: type: string example: req_a1b2c3d4e5f6 timestamp: type: string format: date-time example: '2026-03-10T12:00:00.000Z' ErrorResponse: type: object properties: success: type: boolean example: false error: type: object properties: code: type: string description: Error code example: VALIDATION_ERROR message: type: string description: Human readable error message example: Human readable error message details: type: object description: Optional additional error details meta: $ref: '#/components/schemas/Meta' Meta: type: object properties: requestId: type: string example: req_a1b2c3d4e5f6 timestamp: type: string format: date-time example: '2026-03-10T12:00:00.000Z' securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-KEY description: API key for authentication ````