Attribution Reports API

Save multi-touch attribution reports and compare channel, source, campaign, and term credit across six attribution models.

Attribution reports credit your marketing channels, sources, campaigns, and terms for up to five conversion outcomes. Every result includes credit under first touch, last touch, linear, U-shaped, J-shaped, and time decay models, so you can compare models without running the report again. The Attribution Reports guide covers building and reading these reports in the app.

Updates, duplicates, and deletes take the report's current expectedRevision, and a stale one returns 409 so you never overwrite a teammate's edit. A PATCH replaces any reportContext or definition you send in full, and null clears the description. To compute results, send a saved or draft definition with an inclusive date range of up to 92 days to the preview endpoint; nothing is saved. Structured query parameters are JSON-encoded.

Every number in a result opens the visitors behind it. Send the same definition, dates, comparison, and interval to the visitors endpoint with a selection: the outcome, period, row, touch role, and optionally one chart bucket. The list total matches the number you picked: a first-touch credit of 12 under unique counting opens exactly 12 visitors. Each visitor comes with their credited first and last touch, conversion time, sessions, credit, value, and recent session replays, so you can open their profile or watch what they did. The visitors endpoint requires an API key with the View Visitor permission as well as Analytics Suite access.

To see what moved, send the same input to the insights endpoint. It returns up to eight findings: sources, campaigns, and terms that are new to your account and already earning credit, the largest share-adjusted changes against your comparison period, channels that first and last touch credit very differently, and rows that went quiet. Each finding carries its baseline and sample size, and names the row it is about so you can find it in the preview result. Add a comparison to get every kind of finding; without one you get new values only.

GET/rest/v1/attribution-reports

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?integer

Maximum attribution reports to return. Defaults to 20; values above 100 are capped at 100. Each page scans at most 100 reports in stable ID order, so pages may be short even when more results exist.

cursor?string

Opaque pagination.nextCursor from the previous page, scoped to the account and search text. Continue while pagination.hasMore is true; changing the search requires starting without a cursor.

search?string

Case-insensitive substring search on attribution report names.

Lengthlength <= 200

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/attribution-reports"

{  "entities": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",      "name": "string",      "description": "string",      "reportContext": {        "dateRange": {          "from": "string",          "to": "string",          "timeZone": "UTC"        }      },      "definition": {        "version": 1,        "kind": "attribution",        "outcomes": [          {            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",            "label": "string",            "eventNames": [              "string"            ],            "filter": {              "version": 1,              "filter": {                "kind": "and",                "children": [                  {                    "kind": "and",                    "children": []                  }                ]              }            },            "value": {              "property": "event.properties",              "type": "number",              "path": [                "string"              ]            }          }        ],        "model": "first_touch",        "counting": "unique",        "lookbackDays": 30,        "filter": {          "version": 1,          "filter": {            "kind": "and",            "children": [              {                "kind": "and",                "children": []              }            ]          }        },        "currency": "USD"      },      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "createdByUserId": "string",      "updatedByUserId": "string"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  },  "unavailableCount": 0}

POST/rest/v1/attribution-reports

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Display name for the saved attribution report.

Length1 <= length <= 200

description?|

Optional description; null clears it.

Lengthlength <= 2000

reportContext*

Default UTC date range: a preset or inclusive from/to calendar dates. Replaces the saved context on PATCH. Results cover at most 92 inclusive days.

definition*

Version 1 attribution definition: one to five conversion outcomes, each with one to ten unique event names, an optional filter, and an optional numeric event property summed as value. Set the credit model (default last_touch), counting unit (default unique), lookback window of 7, 14, 30, 60, or 90 days (default 30), an optional filter applied to every outcome, and the value currency (default USD). Outcome ids identify outcomes in results. Replaces the saved definition on PATCH.

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/attribution-reports" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "reportContext": {      "dateRange": {        "from": "string",        "to": "string"      }    },    "definition": {      "version": 1,      "kind": "attribution",      "outcomes": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "label": "string",          "eventNames": [            "string"          ]        }      ]    }  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "definition": {    "version": 1,    "kind": "attribution",    "outcomes": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "label": "string",        "eventNames": [          "string"        ],        "filter": {          "version": 1,          "filter": {            "kind": "and",            "children": [              {                "kind": "and",                "children": []              }            ]          }        },        "value": {          "property": "event.properties",          "type": "number",          "path": [            "string"          ]        }      }    ],    "model": "first_touch",    "counting": "unique",    "lookbackDays": 30,    "filter": {      "version": 1,      "filter": {        "kind": "and",        "children": [          {            "kind": "and",            "children": []          }        ]      }    },    "currency": "USD"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

GET/rest/v1/attribution-reports/{id}

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved attribution report identifier returned by list_attribution_reports or create_attribution_report.

Formatuuid

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/attribution-reports/497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "definition": {    "version": 1,    "kind": "attribution",    "outcomes": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "label": "string",        "eventNames": [          "string"        ],        "filter": {          "version": 1,          "filter": {            "kind": "and",            "children": [              {                "kind": "and",                "children": []              }            ]          }        },        "value": {          "property": "event.properties",          "type": "number",          "path": [            "string"          ]        }      }    ],    "model": "first_touch",    "counting": "unique",    "lookbackDays": 30,    "filter": {      "version": 1,      "filter": {        "kind": "and",        "children": [          {            "kind": "and",            "children": []          }        ]      }    },    "currency": "USD"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

PATCH/rest/v1/attribution-reports/{id}

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved attribution report identifier returned by list_attribution_reports or create_attribution_report.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expectedRevision*string

Current revision from get_attribution_report, list_attribution_reports, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid

name?string

Display name for the saved attribution report.

Length1 <= length <= 200

description?|

Optional description; null clears it.

Lengthlength <= 2000

reportContext?

Default UTC date range: a preset or inclusive from/to calendar dates. Replaces the saved context on PATCH. Results cover at most 92 inclusive days.

definition?

Response Body

`application/json`

curl -X PATCH "https://example.com/rest/v1/attribution-reports/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "expectedRevision": "01b5419f-7ce1-4016-a16c-802ea2b68a5e"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "definition": {    "version": 1,    "kind": "attribution",    "outcomes": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "label": "string",        "eventNames": [          "string"        ],        "filter": {          "version": 1,          "filter": {            "kind": "and",            "children": [              {                "kind": "and",                "children": []              }            ]          }        },        "value": {          "property": "event.properties",          "type": "number",          "path": [            "string"          ]        }      }    ],    "model": "first_touch",    "counting": "unique",    "lookbackDays": 30,    "filter": {      "version": 1,      "filter": {        "kind": "and",        "children": [          {            "kind": "and",            "children": []          }        ]      }    },    "currency": "USD"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

DELETE/rest/v1/attribution-reports/{id}

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved attribution report identifier returned by list_attribution_reports or create_attribution_report.

Formatuuid

Query Parameters

expectedRevision*string

Current revision from get_attribution_report, list_attribution_reports, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid

Response Body

`application/json`

curl -X DELETE "https://example.com/rest/v1/attribution-reports/497f6eca-6276-4993-bfeb-53cbbbba6f08?expectedRevision=497f6eca-6276-4993-bfeb-53cbbbba6f08"

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "deleted": true,  "deletedRevision": "cb5c94d3-b0a8-48db-bf1e-b2828973ba39"}

POST/rest/v1/attribution-reports/{id}/duplicate

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved attribution report identifier returned by list_attribution_reports or create_attribution_report.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

expectedRevision*string

Current revision from get_attribution_report, list_attribution_reports, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid

Response Body

`application/json`

curl -X POST "https://example.com/rest/v1/attribution-reports/497f6eca-6276-4993-bfeb-53cbbbba6f08/duplicate" \  -H "Content-Type: application/json" \  -d '{    "expectedRevision": "01b5419f-7ce1-4016-a16c-802ea2b68a5e"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "definition": {    "version": 1,    "kind": "attribution",    "outcomes": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "label": "string",        "eventNames": [          "string"        ],        "filter": {          "version": 1,          "filter": {            "kind": "and",            "children": [              {                "kind": "and",                "children": []              }            ]          }        },        "value": {          "property": "event.properties",          "type": "number",          "path": [            "string"          ]        }      }    ],    "model": "first_touch",    "counting": "unique",    "lookbackDays": 30,    "filter": {      "version": 1,      "filter": {        "kind": "and",        "children": [          {            "kind": "and",            "children": []          }        ]      }    },    "currency": "USD"  },  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

GET/rest/v1/attribution-reports/preview

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Required input: definition, from, and to; comparison and interval are optional. JSON-encode this object in the REST query string; maximum 16384 bytes before URL encoding. Computing a result never saves or changes a report.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/attribution-reports/preview?input=%7B%22definition%22%3A%7B%22version%22%3A1%2C%22kind%22%3A%22attribution%22%2C%22outcomes%22%3A%5B%7B%22id%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22label%22%3A%22Bookings%22%2C%22eventNames%22%3A%5B%22appointment_booked%22%5D%7D%5D%2C%22model%22%3A%22last_touch%22%2C%22counting%22%3A%22unique%22%2C%22lookbackDays%22%3A30%2C%22currency%22%3A%22USD%22%7D%2C%22from%22%3A%222026-09-01%22%2C%22to%22%3A%222026-09-30%22%2C%22comparison%22%3A%7B%22kind%22%3A%22previous_period%22%7D%7D"

{  "from": "string",  "to": "string",  "previousFrom": "string",  "previousTo": "string",  "interval": "day",  "counting": "unique",  "channelRulesVersion": 1,  "rows": [    {      "grain": "total",      "channel": "string",      "sourceMedium": "string",      "campaign": "string",      "term": "string",      "cells": [        {          "outcomeId": "6c1a48b7-5d9d-4a39-b0dd-22a32d8cc278",          "period": "current",          "credit": {            "first_touch": 0,            "last_touch": 0,            "linear": 0,            "u_shaped": 0,            "j_shaped": 0,            "time_decay": 0          },          "value": {            "first_touch": 0,            "last_touch": 0,            "linear": 0,            "u_shaped": 0,            "j_shaped": 0,            "time_decay": 0          },          "creditedUnits": 0,          "assistedVisitors": 0,          "medianDaysToConvert": 0        }      ]    }  ],  "points": [    {      "bucket": "string",      "period": "current",      "outcomeId": "6c1a48b7-5d9d-4a39-b0dd-22a32d8cc278",      "channel": "string",      "credit": {        "first_touch": 0,        "last_touch": 0,        "linear": 0,        "u_shaped": 0,        "j_shaped": 0,        "time_decay": 0      },      "value": {        "first_touch": 0,        "last_touch": 0,        "linear": 0,        "u_shaped": 0,        "j_shaped": 0,        "time_decay": 0      }    }  ],  "isTruncated": true,  "computedAt": "2019-08-24T14:15:22Z"}

GET/rest/v1/attribution-reports/visitors

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Required input: the same definition, from, to, and optional comparison and interval that produced the result, plus the selection to open; limit and cursor are optional. JSON-encode this object in the REST query string; maximum 16384 bytes before URL encoding.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/attribution-reports/visitors?input=%7B%22definition%22%3A%7B%22version%22%3A1%2C%22kind%22%3A%22attribution%22%2C%22outcomes%22%3A%5B%7B%22id%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22label%22%3A%22Bookings%22%2C%22eventNames%22%3A%5B%22appointment_booked%22%5D%7D%5D%2C%22model%22%3A%22last_touch%22%2C%22counting%22%3A%22unique%22%2C%22lookbackDays%22%3A30%2C%22currency%22%3A%22USD%22%7D%2C%22from%22%3A%222026-09-01%22%2C%22to%22%3A%222026-09-30%22%2C%22comparison%22%3A%7B%22kind%22%3A%22previous_period%22%7D%2C%22selection%22%3A%7B%22outcomeId%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22period%22%3A%22current%22%2C%22grain%22%3A%22source_medium%22%2C%22channel%22%3A%22Paid+search%22%2C%22sourceMedium%22%3A%22google+%2F+cpc%22%2C%22touchRole%22%3A%22last%22%7D%2C%22limit%22%3A25%7D"

{  "entities": [    {      "visitorId": "string",      "convertedAt": "2019-08-24T14:15:22Z",      "units": 1,      "credit": 0,      "value": 0,      "firstTouch": {        "at": "2019-08-24T14:15:22Z",        "sessionId": "string",        "channel": "string",        "sourceMedium": "string",        "campaign": "string",        "term": "string"      },      "lastTouch": {        "at": "2019-08-24T14:15:22Z",        "sessionId": "string",        "channel": "string",        "sourceMedium": "string",        "campaign": "string",        "term": "string"      },      "sessionCount": 0,      "latestReplays": [        {          "sessionId": "string",          "date": "string",          "startedAt": "2019-08-24T14:15:22Z"        }      ]    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  },  "totalCount": 0,  "totalUnits": 0}

GET/rest/v1/attribution-reports/insights

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Required input: definition, from, and to; comparison and interval are optional. Use the same input as the preview to explain what moved in that result. JSON-encode this object in the REST query string; maximum 16384 bytes before URL encoding. Nothing is saved.

Response Body

`application/json`

curl -X GET "https://example.com/rest/v1/attribution-reports/insights?input=%7B%22definition%22%3A%7B%22version%22%3A1%2C%22kind%22%3A%22attribution%22%2C%22outcomes%22%3A%5B%7B%22id%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22label%22%3A%22Bookings%22%2C%22eventNames%22%3A%5B%22appointment_booked%22%5D%7D%5D%2C%22model%22%3A%22last_touch%22%2C%22counting%22%3A%22unique%22%2C%22lookbackDays%22%3A30%2C%22currency%22%3A%22USD%22%7D%2C%22from%22%3A%222026-09-01%22%2C%22to%22%3A%222026-09-30%22%2C%22comparison%22%3A%7B%22kind%22%3A%22previous_period%22%7D%7D"

{  "from": "string",  "to": "string",  "previousFrom": "string",  "previousTo": "string",  "counting": "unique",  "model": "first_touch",  "newValueLookbackDays": 1,  "insights": [    {      "id": "string",      "kind": "new_value",      "evidence": "descriptive",      "outcomeId": "6c1a48b7-5d9d-4a39-b0dd-22a32d8cc278",      "row": {        "grain": "channel",        "channel": "string",        "sourceMedium": "string",        "campaign": "string",        "term": "string"      },      "model": "first_touch",      "current": 0,      "baselineKind": "previous_period",      "baselineModel": "first_touch",      "baseline": 0,      "delta": 0,      "change": 0,      "currentShare": 0,      "baselineShare": 0,      "outcomeChange": 0,      "sampleUnits": 0,      "previousSampleUnits": 0,      "sampleSessions": 0,      "firstSeen": "string",      "drivers": [        "string"      ],      "score": 0    }  ],  "computedAt": "2019-08-24T14:15:22Z"}

Attribution Reports

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

Next Steps

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`