Reporting API Reference

All reports are GET requests under https://api.corvidae.ai/reporting. See Getting Started with the Corvidae API for sign-in, dates, filters and errors.

Access: API key means the report works with an X-API-Key header or a signed-in user token. Token only means it needs a signed-in user token and rejects API keys.

Common parameters

Parameter

Type

Description

companyId

integer

The company to report on. You must have access to it.

startDate, endDate

date (yyyy-MM-dd) or date-time

The period, inclusive. Each report states which format.

conversionTypeIds

integer[]

Only these conversion types. Repeat the parameter. Omit for all.

digitalPropertyIds

integer[]

Only these sites or apps. Repeat the parameter. Omit for all.

modelId

integer

Attribution model. Omit for the company's default.

channelType

text

One of Affiliate, Direct, Display, Email, Native, OrganicSearch, OrganicSocial, PaidSearch, PaidSocial, Referral, Aggregator.

Paid channels: Affiliate, Display, Native, PaidSearch, PaidSocial, Aggregator. Organic channels: Direct, Email, OrganicSearch, OrganicSocial, Referral.

Which report answers which question

Question

Report

How is each channel performing day by day?

Channel performance, Daily performance

How much revenue is paid versus organic?

Channel contribution

Which campaigns, sources or referrers drive revenue?

Primary dimensions, Referrers

How do our numbers compare with the ad platform?

AdTech campaigns

How does the attribution model change channel credit?

Model comparison

Who introduces, influences and closes sales?

IIC

How do we compare with Google Analytics?

Google comparison

What paths do customers take before converting?

Journeys

Where, on what device and when do customers convert?

Audience reports

Did a campaign change cause extra conversions?

Incrementality, Experiments

Report index

Area

Report

Path

Access

Channels

Channel performance

/api/v2/channels/performance

API key


Daily performance

/api/v2/channels/dailyPerformance

API key


Channel contribution

/api/v2/channels/contribution

API key

Traffic

Traffic

/api/v2/traffic

API key

Campaigns

Primary dimensions

/api/v2/primarydimensions

API key


AdTech campaigns

/api/v2/adtechcampaigns

API key


Referrers

/api/v2/referrers

API key

Audience

Cities

/api/v2/audience/cities

API key


Devices

/api/v2/audience/devices

API key


Weekdays

/api/v2/audience/weekday

API key


Hours

/api/v2/audience/hour

API key

Attribution

Model comparison

/api/v2/modelcomparison

API key


IIC

/api/v2/iic

API key


Google comparison

/api/v2/google/comparison

API key


Journeys

/api/v1/journeys

API key


Path length

/vla/pathsLength

Token only


Paths table

/vla/pathsTable

Token only

Raw data

Raw transactions

/api/v2/rawtransactions

API key

Conversion types

List, create

/api/v1/companies/{companyId}/conversionTypes

Token only

Experiments

Experiments, daily revenue

/api/v1/experiments, /api/v1/experiments/dailyrevenue

Token only

Incrementality

Comparisons and results

/api/incrementality/comparisons

Token only

Channel reports

GET /api/v2/channels/performance

Daily visits, unique visitors, conversions, revenue and impressions, with totals for the period. Use it to chart how a channel, or all channels, is trending.

Parameter

Required

Notes

companyId

Yes


startDate, endDate

Yes

yyyy-MM-dd

channelType

No

Omit for all channels.

conversionTypeIds, digitalPropertyIds, modelId

No


uniqueCampaignId

No

Only this campaign.

JSON
{
  "totalVisitCount": 0,
  "totalUniqueVisitorCount": 0,
  "totalConversionCount": 0.0,
  "totalRevenue": 0.0,
  "totalImpressionsCount": 0,
  "dailyData": [
    { "date": "2026-01-01T00:00:00", "visitCount": 0, "uniqueVisitorCount": 0,
      "conversionCount": 0.0, "revenue": 0.0, "impressionsCount": 0 }
  ]
}

The totals are the sums of the daily rows, so a visitor who returns on several days is counted once per day in totalUniqueVisitorCount.

GET /api/v2/channels/dailyPerformance

Attributed revenue per day, split by channel. Use it for a stacked revenue-over-time chart.

Parameters: companyId, startDate, endDate (date-time) required; conversionTypeIds, digitalPropertyIds, campaignId, modelId optional.

Response: one item per channel: { "channel", "totalRevenue", "dailyData": [{ "date", "revenue" }] }.

GET /api/v2/channels/contribution

Each channel's revenue as an amount and a percentage, rolled up into Paid and Organic groups.

Parameters: companyId, startDate, endDate (date-time) required; conversionTypeIds, digitalPropertyIds, modelId optional.

Response: array of { "group", "channel", "revenue", "revenuePercent", "groupRevenue", "groupRevenuePercent" }. revenuePercent is the channel's share of total revenue. groupRevenuePercent is its share of its Paid or Organic group.

GET /api/v2/traffic

The same daily figures as channel performance, for all channels combined, using the company's default attribution model.

Parameters: companyId, startDate, endDate (yyyy-MM-dd) required; conversionTypeIds, digitalPropertyIds optional. Response: same shape as channel performance.

Campaign and source reports

GET /api/v2/primarydimensions

Performance ranked by campaign, source or referrer.

Parameters: companyId, primaryDimension (Campaign, Source or Referrer), startDate, endDate (date-time) required; channelType, conversionTypeIds, digitalPropertyIds, modelId optional.

Response: array of { "primaryDimension", "revenue", "conversionCount", "visitCount", "uniqueVisitorCount" }, where primaryDimension is the name.

GET /api/v2/adtechcampaigns

Compares what Corvidae attributes to each campaign with what the ad platform (for example Google Ads or Meta) reports, including spend and budget. Use it to spot where the two disagree.

Parameters: companyId, startDate, endDate (date-time) required; channelType, conversionTypeIds, digitalPropertyIds, uniqueCampaignId, modelId optional.

Response: one item per campaign.

Group

Fields

Corvidae

campaignId, campaignName, revenue, conversionCount, visitCount, uniqueVisitorCount, roas, cpa

Ad platform

adTech, adTechAccountId, adTechCampaignId, adTechCampaignStatus, adTechCampaignType, adTechCampaignSubType, adTechBudget, adTechBudgetCadence, adTechBiddingStrategy, adTechSpend, adTechRevenue, adTechImpressions, adTechClicks, adTechConversions, adTechAllConversions, adTechRoas, adTechCpa

Differences

conversionsDifference, revenueDifference, roasDifference, cpaDifference (Corvidae minus ad platform)

roas is revenue divided by spend and cpa is spend divided by conversions. Both are 0 when there is no spend or no conversions. The adTech fields are empty for campaigns with no linked ad platform campaign.

GET /api/v2/referrers

Clicks, revenue and conversions for each referring site, with its channel.

Parameters: companyId, startDate, endDate (yyyy-MM-dd) required; conversionTypeIds, digitalPropertyIds optional. Response: array of { "referrer", "channel", "clicks", "revenue", "conversions" }.

Audience reports

Who converts, where, on what and when. All four take companyId, startDate, endDate (yyyy-MM-dd) as required and conversionTypeIds, digitalPropertyIds as optional, and use the company's default attribution model.

Report

Shows

Response item

/api/v2/audience/cities

Revenue by customer city

{ "city", "revenue" }

/api/v2/audience/devices

Revenue by device operating system

{ "osFamily", "revenue" }

/api/v2/audience/weekday

Revenue, conversions, visits and impressions per day of the week

{ "dayOfWeek", "revenue", "conversions", "visits", "impressions" }

/api/v2/audience/hour

The same, per hour of each day (for a heatmap)

{ "dayOfWeek", "hour", "revenue", "conversions", "visits", "impressions" }

dayOfWeek is Monday to Sunday. Location is available at city level only.

Attribution reports

GET /api/v2/modelcomparison

Revenue credited to each channel under each attribution model, side by side.

Parameters: companyId, startDate, endDate (yyyy-MM-dd) required; conversionTypeIds, digitalPropertyIds optional.

Response: totals per model (customerConversionTotal, newCustomerDiscoveryTotal, timeDecayZipfsDecayTotal, firstClickTotal, lastClickTotal, linearClickTotal, timeDecayTotal) and items[], one per channel, with channelName and a revenue value per model.

GET /api/v2/iic

Introducer, influencer and closer analysis: what typically starts customer journeys, assists along the way, or finishes them, and the revenue credited at that stage.

Parameters: companyId, startDate, endDate (yyyy-MM-dd), aggBy (campaign, channel, referer or source), stage (introducer, influencer or closer) required; conversionTypeIds optional.

Response: { "totalRevenue", "totalConversions", "totalRevenuePerConversion", "items": [{ "channel", "campaign", "source", "revenue", "conversions", "revenuePerConversion" }] }.

GET /api/v2/google/comparison

Compares revenue attributed by Corvidae with revenue reported by Google Analytics, per channel and in total.

Parameters: companyId, startDate, endDate (date-time) required.

Response: { "report": [{ "channel", "channelGroup", "revenue", "googleRevenue" }], "totalRevenue", "totalGoogleRevenue" }. revenue is Corvidae-attributed.

GET /api/v1/journeys

The most common customer paths to conversion: ordered channels (optionally with source and campaign), with the conversions and revenue each path produced.

Parameter

Required

Notes

companyId

Yes


startDate, endDate

Yes

yyyy-MM-dd

containsChannels, containsCampaigns, containsSources, containsUniqueCampaignId

No

Paths that include any of these.

startChannel, startCampaign, startSource

No

Paths whose first touchpoint matches.

endChannel, endCampaign, endSource

No

Paths whose last touchpoint matches.

conversionTypeIds, modelId

No


sortColumn

No

RevenueSum or TotalConversions.

sortOrder

No

Descending or Ascending.

aggregationLevel

No

Channel, ChannelSource, ChannelSourceCampaign or ChannelTransition.

Response: { "totalConversions", "totalRevenue", "paths": [{ "conversions", "revenue", "items": [{ "channel", "source", "campaign", "revenuePercentage" }] }] }. revenuePercentage is the share of the path's revenue credited to that step.

Raw data

GET /api/v2/rawtransactions

Individual transactions for a company and period, for reconciliation or export.

Parameters: companyId, startDate, endDate (yyyy-MM-dd) required. Response: array of { "dateTime", "transactionId", "revenue", "shipping", "tax" }.

Reports that need a signed-in user token

These reject API keys. They are used by the Corvidae app and by applications acting for a signed-in user.

Path length: GET /vla/pathsLength

Path-length statistics before and after visitor identity stitching, including single-touch journeys. Parameters: companyId, startDate, endDate (yyyy-MM-dd) required; conversionTypeIds optional.

Paths table: GET /vla/pathsTable

Conversion paths for a chosen attribution model, with conversions, revenue and the revenue split across steps. Parameters: companyId, startDate, endDate, model required; channelType, sourceType, campaignType, conversionTypeIds, campaignId optional. Response: array of { "conversions", "revenue", "attributes": [{ "channel", "source", "campaign", "revenuePercentage" }] }.

Conversion types: /api/v1/companies/{companyId}/conversionTypes

The named events (for example a purchase or sign-up) that reports can be filtered by. The id returned is what you pass as conversionTypeIds.

Method

Purpose

Body or response

GET

List the company's conversion types.

[{ "id", "conversionType" }]

POST

Create one.

{ "conversionType": "string" }, 1 to 100 characters, letters, numbers and - . _ ~ only.

Experiments: /api/v1/experiments

Control-versus-trial results for campaign experiments, comparing Corvidae-attributed and ad platform results. Both reports take companyId, startDate, endDate (date-time) required and conversionTypeIds, digitalPropertyIds, modelId optional.

  • GET /api/v1/experiments returns one entry per experiment, with a combined row, a control row and a trial row, a ROAS chart, the revenue difference and an annualised projection.

  • GET /api/v1/experiments/dailyrevenue returns control and trial revenue per day plus percentage differences in revenue, conversions, media spend and CPA.

Units differ within a response. Control and trial rows hold absolute values. The combined row and the *Difference fields are percentage differences of trial relative to control, (trial - control) / control x 100, or 0 when control is zero. The exception is totalRevenueDifference, an absolute amount.

Incrementality: /api/incrementality/comparisons

Attribution answers which touchpoints get credit for conversions that happened. Incrementality answers how many extra conversions the advertising caused, by comparing a control group of campaigns with an experiment group.

  1. List the company's campaigns and conversion actions with GET /campaignConversionActions?companyId=.

  2. Create a comparison with a control group and an experiment group, each made of campaign and conversion action pairs, and a start date.

  3. Fetch the results to see uplift, the change in CPA and ROAS, daily trends and an annualised projection.

Call

Purpose

GET /campaignConversionActions?companyId=

Campaigns and the conversion actions each has.

POST /

Create a comparison. Returns { "id", "message" }.

GET /?companyId=

List comparisons with a headline summary (conversion and revenue uplift, CPA and ROAS change).

GET /{id}?companyId=

One comparison with its groups.

PUT /{id}

Replace a comparison (same body as create).

DELETE /{id}?companyId=

Delete a comparison.

GET /{id}/results?companyId=

The calculated results.

Create and update body:

JSON
{
  "companyId": 0,
  "name": "string",
  "startDate": "2026-01-01T00:00:00Z",
  "endDate": null,
  "controlGroup":    { "groupName": "Control",    "rows": [{ "campaignId": 0, "conversionActionId": 0 }] },
  "experimentGroup": { "groupName": "Experiment", "rows": [{ "campaignId": 0, "conversionActionId": 0 }] }
}

endDate is optional; leave it out for an open-ended comparison. A missing comparison returns 404, and invalid input returns 400 with a message.

The results include totals for each group, the uplift (conversionUpliftPercent, revenueUpliftPercent), differences in spend, conversions and revenue (experiment minus control), CPA and ROAS, per-action figures, an annualised projection, daily trends and per-campaign figures. Uplift, CPA and ROAS are empty when the value they are divided by is zero.