> ## Documentation Index > Fetch the complete documentation index at: https://docs.api.aura-app.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get per-ad funnel performance > > **Alpha API** - This endpoint is in active development. Schema may change without notice. One row per AD — campaign, ad set and ad — with the funnel an ad buyer reads left to right: leads, qualified, disqualified, booked, attended, closed, and both revenue measures. Finer than `/campaigns`, which stops at campaign. **Three things it deliberately does not do:** - **No spend, so no ROAS or CAC.** Aura stores no ad cost, so those are not computable here. Ranking on revenue and calling it return on ad spend invents the denominator. - **Ad identity rides on UTM columns by convention** (`utm_campaign`, `utm_term`, `utm_content`). A call whose link omitted them is absent entirely rather than bucketed as unknown, so totals here can be lower than `/dashboard`. When `ad` and `ad_set` are null across every row, these are campaigns, not ads. - **Two window anchors in one row.** Lead counts are windowed on when the LEAD was created; call counts on when the CALL was scheduled. So `lead_to_book_rate` divides one population by another and can exceed 100, and `booked_calls` here is not comparable to `booked_calls` on `/campaigns`. > **Alpha API** - This endpoint is in active development. Schema may change without notice. One row per AD — campaign, ad set and ad — with the funnel an ad buyer reads left to right: leads, qualified, disqualified, booked, attended, closed, and both revenue measures. Finer than `/campaigns`, which stops at campaign. **Three things it deliberately does not do:** * **No spend, so no ROAS or CAC.** Aura stores no ad cost, so those are not computable here. Ranking on revenue and calling it return on ad spend invents the denominator. * **Ad identity rides on UTM columns by convention** (`utm_campaign`, `utm_term`, `utm_content`). A call whose link omitted them is absent entirely rather than bucketed as unknown, so totals here can be lower than `/dashboard`. When `ad` and `ad_set` are null across every row, these are campaigns, not ads. * **Two window anchors in one row.** Lead counts are windowed on when the LEAD was created; call counts on when the CALL was scheduled. So `lead_to_book_rate` divides one population by another and can exceed 100, and `booked_calls` here is not comparable to `booked_calls` on `/campaigns`. ## OpenAPI ````yaml openapi.json GET /v1/analytics/ad-performance openapi: 3.1.0 info: contact: email: support@aura-app.ai name: Aura Support description: >- # Aura Partner Integrations API > **Alpha Release** - This API is under active development. Endpoints, request/response schemas, and behaviors may change without prior notice. We recommend pinning to specific response fields you need and handling unknown fields gracefully. Enterprise REST API for external partner integrations including commission platforms, external mobile apps, and client booking widgets. ## MCP Connector Aura also exposes a **Model Context Protocol** server at `/mcp` so AI assistants (Claude, ChatGPT) can answer questions about a user's own sales data. If you are building an assistant integration rather than a server-to-server one, that is almost certainly the surface you want — it is task-shaped ("prep me for my next call") rather than resource-shaped, and it handles auth per-user. Read-only. OAuth 2.1 + PKCE, with Clerk as the authorization server; discover it from `/.well-known/oauth-protected-resource`. Setup guide: https://docs.api.aura-app.ai/mcp-connector ## Authentication Authenticated endpoints support two authentication methods: **1. API Key (for partners and integrations):** ``` Authorization: Bearer aura_pk_live_xxxxxxxxxxxxxxxx ``` Get your API key from the Aura dashboard at Settings > API Keys. **2. Clerk JWT (for mobile and web apps):** ``` Authorization: Bearer ``` Use Clerk's authentication SDK to obtain a JWT token with org claims. ## Rate Limiting - **Per API Key:** 100 requests/minute - **Per Organization:** 1000 requests/minute Rate limit headers are included in all responses: - `X-RateLimit-Limit`: Maximum requests allowed - `X-RateLimit-Remaining`: Remaining requests in current window - `X-RateLimit-Reset`: Unix timestamp when limit resets These counters are held per serving instance, so under concurrency the effective ceiling is higher than the number above and the headers describe one instance's view rather than a global total. Treat a 429 as backpressure to obey and pace your client to the documented rate — but do not rely on us to reject your 101st request, and do not derive a global remaining-quota figure from the headers. The limit may become globally enforced without notice, so a client that stays within it will not be affected when that happens. ## Pagination List endpoints support cursor-based pagination: - `limit`: Number of results per page (default: 50, max: 100) - `cursor`: Opaque cursor for next page ## Error Handling All errors follow a standard format: ```json { "success": false, "error": "Error message", "code": "ERROR_CODE" } ``` Common HTTP status codes: - **400** Bad Request - Invalid input (`VALIDATION_ERROR`) - **401** Unauthorized - Missing or invalid API key (`AUTHENTICATION_ERROR`) - **402** Payment Required - The key is valid, but the organization's subscription is not active (`PAYMENT_REQUIRED`). Every authenticated endpoint can return this. Retrying will not help until the account's payment method is updated in Aura; surface it to the account owner rather than treating it as an auth failure. - **403** Forbidden - Insufficient permissions (`AUTHORIZATION_ERROR`) - **404** Not Found - Resource not found (`NOT_FOUND`) - **409** Conflict - Resource state prevents the operation (`CONFLICT`) - **413** Payload Too Large - Request body exceeds 256KB (`PAYLOAD_TOO_LARGE`) - **429** Too Many Requests - Rate limit exceeded (`RATE_LIMIT_EXCEEDED`) - **500** Internal Server Error - Server error (`INTERNAL_ERROR`) ## Webhooks Subscribe to real-time events using the Webhooks API. All webhook payloads are signed with HMAC-SHA256 for security verification. Delivery is at-least-once. Every payload carries an `idempotency_key` that is stable across retries of the same event, so you can enforce exactly-once with a `(subscription_id, idempotency_key)` unique constraint on your side. For full documentation, visit [docs.aura-app.ai/api](https://docs.aura-app.ai/api) license: name: Proprietary title: Aura Partner Integrations API version: 1.0.0-alpha servers: - description: Production url: https://api.aura-app.ai - description: Staging url: https://staging-api.aura-app.ai - description: Local Development url: http://localhost:3001 security: - bearerAuth: [] tags: - description: Lead management operations name: Leads - description: Call booking and management name: Calls - description: Booking link configuration (read-only) name: Booking Links - description: Product catalog (read-only) name: Products - description: Payment tracking (read-only) name: Payments - description: Public booking creation name: Bookings - description: Real-time event subscriptions and webhook management name: Webhooks - description: >- Team member information for commission attribution. **Alpha** - schema may change without notice. name: Team (Alpha) - description: >- Dashboard analytics, lead source attribution, and objection analysis. **Alpha** - schema may change without notice. name: Analytics (Alpha) - description: System endpoints (health checks) name: System paths: /v1/analytics/ad-performance: get: tags: - Analytics (Alpha) summary: Get per-ad funnel performance description: >- > **Alpha API** - This endpoint is in active development. Schema may change without notice. One row per AD — campaign, ad set and ad — with the funnel an ad buyer reads left to right: leads, qualified, disqualified, booked, attended, closed, and both revenue measures. Finer than `/campaigns`, which stops at campaign. **Three things it deliberately does not do:** - **No spend, so no ROAS or CAC.** Aura stores no ad cost, so those are not computable here. Ranking on revenue and calling it return on ad spend invents the denominator. - **Ad identity rides on UTM columns by convention** (`utm_campaign`, `utm_term`, `utm_content`). A call whose link omitted them is absent entirely rather than bucketed as unknown, so totals here can be lower than `/dashboard`. When `ad` and `ad_set` are null across every row, these are campaigns, not ads. - **Two window anchors in one row.** Lead counts are windowed on when the LEAD was created; call counts on when the CALL was scheduled. So `lead_to_book_rate` divides one population by another and can exceed 100, and `booked_calls` here is not comparable to `booked_calls` on `/campaigns`. parameters: - description: ISO 8601 start date (defaults to all time) in: query name: start_date required: false schema: description: ISO 8601 start date (defaults to all time) example: '2026-01-01T00:00:00Z' type: string - description: ISO 8601 end date (defaults to now) in: query name: end_date required: false schema: description: ISO 8601 end date (defaults to now) example: '2026-03-19T23:59:59Z' type: string responses: '200': content: application/json: schema: $ref: '#/components/schemas/AdPerformanceSuccessResponse' description: Successfully retrieved ad performance '400': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: Request validation failed headers: X-Request-Id: description: Request identifier for support schema: type: string '401': content: application/json: schema: $ref: '#/components/schemas/AnalyticsErrorResponse' description: Invalid or missing API key '402': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The organization's subscription is not active headers: X-Request-Id: description: Request identifier for support schema: type: string '403': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The API key does not have the required scope headers: X-Request-Id: description: Request identifier for support schema: type: string '408': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- The request exceeded its processing time limit. Check the outcome before retrying a write headers: X-Request-Id: description: Request identifier for support schema: type: string '413': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: The request body exceeds 256KB headers: X-Request-Id: description: Request identifier for support schema: type: string '422': content: application/json: schema: $ref: '#/components/schemas/AnalyticsErrorResponse' description: >- Currency is missing or more than one currency is present. Use /v1/analytics/revenue for grouped amounts. '429': content: application/json: schema: $ref: '#/components/schemas/AnalyticsErrorResponse' description: Rate limit exceeded '500': content: application/json: schema: $ref: '#/components/schemas/MiddlewareErrorResponse' description: >- Unexpected server failure. Include the request identifier when contacting support headers: X-Request-Id: description: Request identifier for support schema: type: string security: - bearerAuth: [] components: schemas: AdPerformanceSuccessResponse: properties: data: items: $ref: '#/components/schemas/AdPerformance' type: array success: enum: - true type: boolean required: - success - data type: object MiddlewareErrorResponse: properties: code: type: string error: type: string requestId: type: string success: enum: - false type: boolean required: - success - error - code type: object AnalyticsErrorResponse: properties: code: description: Error code for programmatic handling example: DATABASE_ERROR type: string error: description: Human-readable error message example: Failed to fetch analytics type: string requestId: description: Request ID for support debugging example: req_abc123 type: string success: enum: - false type: boolean required: - success - error - code type: object AdPerformance: properties: ad: description: >- utm_content by convention. Null when the link did not set it — and when it is null across every row, these are campaigns, not ads. example: video-a nullable: true type: string ad_set: description: utm_term by convention. Null when the link did not set it. example: lookalike-1pct nullable: true type: string attended_calls: example: 18 type: number book_to_attend_rate: example: 60 nullable: true type: number booked_calls: description: >- Calls SCHEDULED in the window. NOT comparable to booked_calls on /campaigns or /lead-sources, which count calls belonging to leads created in the window. example: 30 type: number booked_revenue: description: Every sale row on the closed calls — what was signed. example: 12000 type: number campaign: example: spring-2026 type: string close_rate: example: 33.3 nullable: true type: number closed_calls: example: 6 type: number collected_revenue: description: Settled sale rows only — what arrived. example: 9500 type: number currency: description: Recorded currency for the legacy scalar totals. type: string disqualified_leads: example: 20 type: number lead_to_book_rate: description: >- Calls per lead generated, as a percentage. Numerator and denominator use DIFFERENT window anchors, so this can legitimately exceed 100 — read it as calls per lead, not a conversion rate, and do not normalise it to 100. example: 25 nullable: true type: number leads_generated: description: >- Leads CREATED in the window that booked an attributed call. Windowed on leads.created_at, unlike the call counts below. example: 120 type: number medium: example: cpc nullable: true type: string meta_ad_id: description: >- The finest attribution grain Aura records. Null when the bucket saw none AND when it saw several — the second means the UTM triple is not identifying one ad. example: '1234567890' nullable: true type: string qualified_leads: example: 100 type: number revenue_summary: $ref: '#/components/schemas/RevenueSummary' source: example: facebook nullable: true type: string required: - revenue_summary - currency - campaign - ad_set - ad - source - medium - meta_ad_id - leads_generated - qualified_leads - disqualified_leads - booked_calls - attended_calls - closed_calls - booked_revenue - collected_revenue - lead_to_book_rate - book_to_attend_rate - close_rate type: object RevenueSummary: description: >- Unique sales grouped by recorded currency. Missing or conflicting currency amounts are separate. No exchange rate is applied. properties: by_currency: items: properties: booked_amount: type: number collected_amount: type: number currency: type: string sale_count: minimum: 0 type: integer required: - booked_amount - collected_amount - sale_count - currency type: object type: array missing_currency: properties: booked_amount: type: number collected_amount: type: number sale_count: minimum: 0 type: integer required: - booked_amount - collected_amount - sale_count type: object required: - by_currency - missing_currency type: object ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.