get_campaigns_report
Retrieve campaign performance reports from Ogury's API with date ranges and filtering options to analyze advertising effectiveness.
Instructions
Get campaign performance report with flexible filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| accountId | No | Account IDs (comma-separated) | |
| brandId | No | Brand ID | |
| campaignId | No | Campaign ID | |
| endDate | Yes | End date in YYYY-MM-DD format (required) | |
| identifier1 | No | External identifier 1 | |
| identifier2 | No | External identifier 2 | |
| identifier3 | No | External identifier 3 | |
| startDate | Yes | Start date in YYYY-MM-DD format (required) |
Implementation Reference
- src/index-stdio.ts:291-364 (handler)The core handler function for the 'get_campaigns_report' tool. It authenticates via getAccessToken, constructs query params from input args, fetches data from the Ogury API endpoint /v1/reporting/campaigns, handles single or array response, formats numbers/percentages, builds a text report summarizing campaigns, and returns MCP-formatted content.
private async getCampaignsReport(args: { startDate: string; endDate: string; accountId?: string; brandId?: string; campaignId?: number; identifier1?: string; identifier2?: string; identifier3?: string; }) { const token = await this.getAccessToken(); const params = new URLSearchParams({ startDate: args.startDate, endDate: args.endDate, }); if (args.accountId) params.append('accountId', args.accountId); if (args.brandId) params.append('brandId', args.brandId); if (args.campaignId) params.append('campaignId', args.campaignId.toString()); if (args.identifier1) params.append('identifier1', args.identifier1); if (args.identifier2) params.append('identifier2', args.identifier2); if (args.identifier3) params.append('identifier3', args.identifier3); try { const response = await fetch(`${this.baseUrl}/v1/reporting/campaigns?${params}`, { method: 'GET', headers: { 'Authorization': `Bearer ${token}`, 'Accept': 'application/json', }, }); if (!response.ok) { throw new Error(`API request failed: ${response.status} ${response.statusText}`); } const campaignData: CampaignReport | CampaignReport[] = await response.json(); const campaigns = Array.isArray(campaignData) ? campaignData : [campaignData]; // Safe number formatting with null checks const formatNumber = (value: any) => { if (value === null || value === undefined) return 'N/A'; return typeof value === 'number' ? value.toLocaleString() : String(value); }; const formatPercentage = (value: any) => { if (value === null || value === undefined) return 'N/A'; return typeof value === 'number' ? `${value}%` : String(value); }; const report = campaigns.map(campaign => `Campaign ID: ${campaign.campaignId || 'N/A'} | ${campaign.campaign || 'N/A'} Brand: ${campaign.brand || 'N/A'} | Strategy: ${campaign.strategy || 'N/A'} Impressions: ${formatNumber(campaign.impressions)} | Clicks: ${formatNumber(campaign.clicks)} | CTR: ${formatPercentage(campaign.ctr)} Spend: ${formatNumber(campaign.spend)} ${campaign.currency || ''} | Reach: ${formatNumber(campaign.reach)} `).join('\n---\n'); return { content: [ { type: 'text', text: `Campaigns Report (${args.startDate} to ${args.endDate}): ${report} Total campaigns: ${campaigns.length}`, }, ], }; } catch (error) { throw new Error(`Failed to fetch campaigns report: ${error instanceof Error ? error.message : 'Unknown error'}`); } } - src/index-stdio.ts:102-142 (schema)Input schema and metadata for the get_campaigns_report tool, defining parameters for date range and optional filters (account, brand, campaign ID, external identifiers). Used in tools/list response.
name: 'get_campaigns_report', description: 'Get campaign performance report with flexible filtering', inputSchema: { type: 'object', properties: { startDate: { type: 'string', description: 'Start date in YYYY-MM-DD format (required)', }, endDate: { type: 'string', description: 'End date in YYYY-MM-DD format (required)', }, accountId: { type: 'string', description: 'Account IDs (comma-separated)', }, brandId: { type: 'string', description: 'Brand ID', }, campaignId: { type: 'number', description: 'Campaign ID', }, identifier1: { type: 'string', description: 'External identifier 1', }, identifier2: { type: 'string', description: 'External identifier 2', }, identifier3: { type: 'string', description: 'External identifier 3', }, }, required: ['startDate', 'endDate'], }, }, - src/index-stdio.ts:148-170 (registration)Tool dispatch registration via setRequestHandler(CallToolRequestSchema). The switch case routes 'get_campaigns_report' calls to the getCampaignsReport handler.
this.server.setRequestHandler(CallToolRequestSchema, async (request) => { const { name, arguments: args } = request.params; try { switch (name) { case 'get_campaign_details': return await this.getCampaignDetails(args as any); case 'get_campaigns_report': return await this.getCampaignsReport(args as any); default: throw new Error(`Unknown tool: ${name}`); } } catch (error) { return { content: [ { type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error occurred'}`, }, ], }; } }); - src/index-stdio.ts:71-147 (registration)Tool list registration via setRequestHandler(ListToolsRequestSchema), including get_campaigns_report in the available tools list with its schema.
{ name: 'get_campaign_details', description: 'Get campaign performance details by campaign ID', inputSchema: { type: 'object', properties: { campaignId: { type: 'number', description: 'The campaign ID to retrieve details for', }, startDate: { type: 'string', description: 'Start date in YYYY-MM-DD format (required)', }, endDate: { type: 'string', description: 'End date in YYYY-MM-DD format (required)', }, accountId: { type: 'string', description: 'Optional account ID filter', }, brandId: { type: 'string', description: 'Optional brand ID filter', }, }, required: ['campaignId', 'startDate', 'endDate'], }, }, { name: 'get_campaigns_report', description: 'Get campaign performance report with flexible filtering', inputSchema: { type: 'object', properties: { startDate: { type: 'string', description: 'Start date in YYYY-MM-DD format (required)', }, endDate: { type: 'string', description: 'End date in YYYY-MM-DD format (required)', }, accountId: { type: 'string', description: 'Account IDs (comma-separated)', }, brandId: { type: 'string', description: 'Brand ID', }, campaignId: { type: 'number', description: 'Campaign ID', }, identifier1: { type: 'string', description: 'External identifier 1', }, identifier2: { type: 'string', description: 'External identifier 2', }, identifier3: { type: 'string', description: 'External identifier 3', }, }, required: ['startDate', 'endDate'], }, }, ], }; }); // Handle tool calls - src/index-stdio.ts:173-203 (helper)Shared helper function to obtain and cache OAuth2 access token using client credentials, used by the handler for API authentication.
private async getAccessToken(): Promise<string> { // Check if token is still valid (with 5 minute buffer) if (this.accessToken && this.tokenExpiry && Date.now() < this.tokenExpiry - 300000) { return this.accessToken; } const credentials = Buffer.from(`${this.clientId}:${this.clientSecret}`).toString('base64'); try { const response = await fetch(`${this.baseUrl}/oauth2/token`, { method: 'POST', headers: { 'Authorization': `Basic ${credentials}`, 'Content-Type': 'application/x-www-form-urlencoded', }, body: 'grant_type=client_credentials', }); if (!response.ok) { throw new Error(`Authentication failed: ${response.status} ${response.statusText}`); } const authData: AuthResponse = await response.json(); this.accessToken = authData.access_token; this.tokenExpiry = Date.now() + (authData.expires_in * 1000); return this.accessToken; } catch (error) { throw new Error(`Failed to get access token: ${error instanceof Error ? error.message : 'Unknown error'}`); } }