Public API

Pathfinder's Public API enables users to access their data in a programmatic way. The API is RESTful and uses JSON data encoding for request and response bodies.

Authentication

To get started, create an API Key for your user in Pathfinder. The API Key will carry your user's identity, and will have access rights to

data which you have access rights to, in either consumer or owner role, or
a subset of the data which you have access rights to, which you can define for the key.

If needed, you can define the expiration date/time for the API Key. Otherwise, the key will be valid until it's deactivated via Pathfinder.

Later, you can edit or delete any of the API Keys you have created. Any modification to the access rights will be effective immediately.

When calling the endpoints, put the API Key in the HTTP headers like this:

GET /v1/me HTTP/1.1
X-API-Key: 123456789.abcdefghijklmnopqrstuxyz

Conventions

All endpoints respond with a JSON-encoded object in the body. The shapes of the objects vary between endpoints and are described in greater detail in the endpoint reference section.

For endpoints responding with lists:

The response body object extends the following interface:

interface ListResponseBodyObject {
  /** The number of the page included in the response. First page is 0. */
  page: number;
  /** The total number of pages available on the server. */
  pages: number;
  /** An array containing the actual objects included in the response. */
  data: object[];
}

The number of objects per page (page size) is fixed, but vary between endpoints. The fixed number is stated in the endpoint reference section for the respective endpoint.
The endpoints accept a URL search param page to retreive a page other than the first page in the result set.

Errors

The API uses HTTP response codes to indicate the success or failure of an API request. Success is indicated with codes in the 2xx range. Other ranges indicate error.

If an error occurs, the response will contain a special error response body object instead of the normal response body object for the endpoint:

interface ErrorResponseBodyObject {
  /** Error message. */
  error: string;
}

Reference

Base URL

The base URL for the API is https://pathfinder.viomba.com/api/public/v1.

Endpoints

`GET /me`

Retrieves information about the user who created the API Key.

interface MeResponseBodyObject {
  /** Globally unique identifier for the user. */
  id: number;
  /** The user's email address. */
  email: string;
  /** The user's given name. */
  first_name: string;
  /** The user's family name. */
  last_name: string;
}

`GET /accounts`

Retrieves the list of accounts available to the API key. The page size is 30 objects per page.

interface AccountsResponseBodyObject extends ListResponseBodyObject {
  data: Account[];
}

`Account`

interface Account {
  /**
   * Globally unique identifier for the account.
   */
  id: number;
  /**
   * Name of the account.
   * (Not unique.)
   */
  name: string;
  /**
   * The ID of the parent account,
   * if this is a child account.
   */
  parent_id?: number;
  /**
   * Two-letter ISO 3166 country of the account.
   * For example "DE".
   */
  country_code: number;
  /**
   * Object containing details about the trading
   * currency of the account.
   */
  currency: {
    /**
     * Three-letter ISO 4217 code of the
     * trading currency.
     */
    code: string;
    /**
     * Symbol representing the trading currency.
     */
    symbol: string;
    /**
     * Symbol representing the trading currency.
     */
    decimals: string;
  };
  /**
   * IANA time zone of the account.
   * For example "Europe/Berlin".
   */
  time_zone: string;
}

`GET /measurements`

Retrieves the list of measurements available to the API key. The page size is 30 objects per page.

interface MeasurementsResponseBodyObject extends ListResponseBodyObject {
  data: Measurement[];
}

`Measurement`

interface Measurement {
  /**
   * Globally unique identifier for the measurement.
   */
  id: number;
  /**
   * Name given to the measurement.
   */
  name?: string;
  /**
   * Date/time when the measurement was created
   * in Pathfinder. Format: YYYY-MM-DDTHH:mm:ssZ.
   */
  created: string;
  /**
   * The state of the measurement.
   */
  state: "draft" | "active" | "archived";
  /**
   * The ID of the account of the measurement.
   */
  account_id: number;
  /**
   * Object containing details about the advertiser
   * of the account.
   */
  advertiser?: {
    /**
     * Globally unique identifier for the advertiser.
     */
    id: number;
    /**
     * Name given to the advertiser.
     * (Not unique.)
     */
    name: string;
  };
  /**
   * The total count of creatives in the measurement.
   */
  creative_count: number;
}

`GET /measurements/:id/creatives`

Retrieves all the creatives in a measurement. THe page size is 30 objects per page.

performance and siteTable will be available only if the measurement of the creative was successful. The performance object details the ad's performance in general, whereas the siteTable contains the performance on each publisher domain separately.

interface CreativesResponseBodyObject extends ListResponseBodyObject {
  data: Creative[];
}

`Creative`

interface Creative {
  /**
   * Globally unique identifier for the creative.
   */
  id: number;
  /**
   * Name given to the creative.
   */
  name?: string;
  /**
   * Date/time when the creative was created
   * in Pathfinder. Format: YYYY-MM-DDTHH:mm:ssZ.
   */
  created: string;
  /**
   * The state of the creative.
   */
  state: "draft" | "rendering" | "ready" | "failed";
  /**
   * If state is "failed", an error message why the creative failed.
   */
  error_message?: string;
  /**
   * The type of the creative.
   */
  type: "html5" | "tag" | "image";
  /**
   * The size of the creative.
   */
  size: {
    /**
     * The width of the creative in pixels.
     */
    width: number;
    /**
     * The height of the creative in pixels.
     */
    height: number;
  };
  /**
   * Array containing objects containing details about the ad's performance in general.
   * Only available once the creative has finished rendering.
   */
  performance?: Array<{
    /**
     * The version of the model used to predict
     * the performance of the ad.
     */
    model_version: number;
    /**
     * The device class to which the entry is applicable.
     */
    device: "desktop" | "mobile";
    /**
     * The likelihood of the ad being seen for each
     * impression in the given conditions.
     * The value is always between 0 and 1.
     */
    seen: number;
    /**
     * Share of impressions impressions which will be viewed
     * for at least 3000 ms (3 seconds).
     * The value is always between 0 and 1.
     */
    seen_3000: number;
    /**
     * Share of impressions impressions which will be viewed
     * for at least 6500 ms (6.5 seconds).
     * The value is always between 0 and 1.
     */
    seen_6500: number;
    /**
     * Share of impressions impressions which will be viewed
     * for at least 8500 ms (8.5 seconds).
     * The value is always between 0 and 1.
     */
    seen_8500: number;
  }>;
  /**
   * An array containing site table entries, which depict
   * the ad's performance on each publisher domain separately.
   * Only available if the measurement of the creative was successful.
   */
  site_table?: Array<{
    /**
     * The domain to which the entry is applicable.
     */
    domain: string;
    /**
     * The device class to which the entry is applicable.
     */
    device: "desktop" | "mobile";
    /**
     * The measured likelihood of the ad being seen for each
     * impression in the given conditions (domain + device).
     * The value is always between 0 and 1.
     */
    seen: number;
    /**
     * The average seen-value for other comparable ads
     * in the same country and size.
     */
    benchmark: number;
  }>;
}

`GET /campaigns`

Retrieves a list of campaigns available to the API Key. The page size is 30 objects per page.

interface CampaignsResponseBodyObject extends ListResponseBodyObject {
  data: Campaigns[];
}

`Campaign`

interface Campaign {
  /**
   * Globally unique identifier for the campaign
   * assigned by Pathfinder.
   */
  id: number;
  /**
   * Name given to the campaign.
   */
  name?: string;
  /**
   * Date/time when the campaign was created
   * in Pathfinder. Format: YYYY-MM-DDTHH:mm:ssZ.
   */
  created: string;
  /**
   * The ID of the account of the campaign.
   */
  account_id: number;
  /**
   * The name of the advertising system where the campaign
   * was published, for example, "dv360".
   */
  advertising_system?: string;
  /**
   * The ID of the campaign in the advertising system.
   */
  external_id?: string;
  /**
   * Object containing the start and end dates of
   * the campaign.
   */
  dates: {
    /**
     * Date when the campaign was launched to the public.
     * Format: YYYY-MM-DD.
     */
    start: string;
    /**
     * Date which was the last active date in the campaign.
     * Format: YYYY-MM-DD.
     */
    end: string;
  };
  /**
   * Object containing details about the advertiser
   * of the campaign.
   */
  advertiser?: {
    /**
     * The ID assigned by the advertising system
     * to the advertiser.
     */
    id: number;
    /**
     * Name given to the advertiser in the
     * advertising system.
     */
    name: string;
  };
  /**
   * Array containing the IDs of the creatives that
   * have been published to this campaign.
   */
  creatives: number[];
}

`POST /campaigns/:campaignId/reports`

Orders a new report.

Param	Description
`:campaignId`	The ID of the campaign from which the report is to be generated.

interface ReportRequestBodyObject {
  /**
   * The source of the report data.
   */
  source: "dsp" | "tracking_pixel";
  /**
   * Object containing the start and end dates of
   * the report.
   */
  dates: {
    /**
     * The first date to be included in the report.
     * Format: YYYY-MM-DD.
     */
    start: string;
    /**
     * The last date to be included in the report.
     * Format: YYYY-MM-DD.
     */
    end: string;
  };
  /**
   * List of dimensions to be included in the report.
   * There has to be at least 1 dimension.
   */
  dimensions: string[];
  /**
   * List of fields to be included in the report.
   */
  dimensions: string[];
  /**
   * List of filters to be applied on the dimensions.
   * Either include or exclude must be specified on each filter object.
   */
  filters: Array<{
    /**
     * Dimension on which the filter is to be applied.
     */
    dimension: string;
    /**
     * List of the values to be included in the report.
     * There has to be at least 1 value given.
     */
    include?: string[];
    /**
     * List of the values to be excluded from the report.
     * There has to be at least 1 value given.
     */
    exclude?: string[];
  }>;
  /**
   * If set to `true`, rows with 100 impressions or less,
   * are omitted.
   */
  optimize?: boolean;
}

The response body object definition is a Report.

`GET /campaigns/:campaignId/reports`

Retrieves the list of reports of campaign :campaignId available to the API Key. The page size is 30 objects per page.

Param	Description
`:campaignId`	The ID of the campaign from which the report was generated.

interface ReportsResponseBodyObject extends ListResponseBodyObject {
  data: Report[];
}

`Report`

interface Report {
  /**
   * Globally unique identifier for the report.
   */
  id: number;
  /**
   * The source of the report data.
   */
  source: "dsp" | "tracking_pixel";
  /**
   * Object containing the start and end dates of
   * the report.
   */
  dates: {
    /**
     * The first date included in the report.
     * Format: YYYY-MM-DD.
     */
    start: string;
    /**
     * The last date included in the report.
     * Format: YYYY-MM-DD.
     */
    end: string;
  };
  /**
   * List of dimensions included in the report.
   */
  dimensions: string[];
  /**
   * List of fields included in the report.
   */
  fields: string[];
  /**
   * List of filters applied on the dimensions.
   * Either include or exclude is specified on each filter object.
   */
  filters: Array<{
    /**
     * Dimension on which the filter is applied.
     */
    dimension: string;
    /**
     * List of the values included in the report.
     */
    include?: string[];
    /**
     * List of the values excluded from the report.
     */
    exclude?: string[];
  }>;
  /**
   * If `true`, rows with 100 impressions or less,
   * are omitted from this report.
   */
  optimize: boolean;
}

`GET /reports/:id/rows`

Retrieves the rows of the report with the given ID. The page size is 500 rows per page.

interface ReportRowsResponseBodyObject extends ListResponseBodyObject {
  data: ReportRow[];
}

`ReportRow`

interface ReportRow {
  /**
   * The date dimension to which the row applies to.
   */
  date?: string;
  /**
   * The pathfinder_creative dimension to which the row applies to.
   */
  pathfinder_creative?: string;
  /**
   * The ad dimension to which the row applies to.
   */
  ad?: string;
  /**
   * The placement dimension to which the row applies to.
   */
  placement?: string;
  /**
   * The creative dimension to which the row applies to.
   */
  creative?: string;
  /**
   * The device dimension to which the row applies to.
   */
  device?: string;
  /**
   * The domain dimension to which the row applies to.
   */
  domain?: string;
  /**
   * The insertion_order dimension to which the row applies to.
   */
  insertion_order?: string;
  /**
   * The line_item dimension to which the row applies to.
   */
  line_item?: string;
  /**
   * The number of impressions on the row.
   */
  impressions?: number;
  /**
   * The estimated number of seen impressions on the row.
   */
  seen_impressions?: number;
  /**
   * The benchmark estimated number of seen impressions on the row.
   */
  benchmark_seen_impressions?: number;
  /**
   * The number of IAB viewable impressions on the row.
   */
  viewable_impressions?: number;
  /**
   * The number of IAB viewable impressions on the row
   * calculated using the legacy viewability measurement technique.
   */
  legacy_viewable_impressions?: number;
  /**
   * The number of clicks on the row.
   */
  clicks?: number;
  /**
   * The amount of spend on the row.
   */
  spend?: number;
  /**
   * The amount of calculated spend on the row.
   */
  calculated_spend?: number;
}

Dimensions

The available dimensions for the dimension selection and filters include:

Dimension	Description
`"date"`	The date of the ad impression. Given in ISO 8601 format. For example `"2023-05-25"`.
`"pathfinder_creative"`	The ID of the creative in Pathfinder.
`"ad"`	The ID of the ad in Meta's advertising system.
`"placement"`	The placement of the ad in Meta's advertising system.
`"creative"`	The ID of the creative in the advertising system.
`"device"`	The device class of the consumer. Either `"desktop"` or `"mobile"`.
`"domain"`	The domain of the publisher website, for example, `"cnn.com"`.
`"insertion_order"`	The ID of the insertion order in the advertising system.
`"line_item"`	The ID of the line item in the advertising system.

Some dimensions are only available given certain conditions:

Dimension	Source: DSP (DV360)	Source: DSP (Xandr)	Source: DSP (Adform)	Source: DSP (Meta)	Source: Tracking Pixel
`"date"`	✅	✅	✅	✅	✅
`"pathfinder_creative"`	✅	✅	✅	✅	✅
`"ad"`				✅
`"placement"`				✅
`"creative"`	✅	✅	✅		✅
`"device"`	✅	✅	✅		✅
`"domain"`	✅	✅	✅		✅
`"insertion_order"`	✅		✅
`"line_item"`	✅		✅

Fields

The available fields for the field selection include:

Field	Description
`"impressions"`	The number of impressions. Always a positive integer.
`"seen_impressions"`	The estimated number of seen impressions.
`"benchmark_seen_impressions"`	The benchmark estimated number of seen impressions.
`"viewable_impressions"`	The number of IAB viewable impressions.
`"legacy_viewable_impressions"`	The number of IAB viewable impressions calculated using the legacy viewability measurement technique.
`"clicks"`	The number of clicks on the ad as reported by the DSP.
`"conversions"`	The number of conversions as reported by the DSP.
`"spend"`	The spend as reported by the DSP.
`"calculated_spend"`	The estimated spend.

note

seen_impressions, benchmark_seen_impressions, viewable_impressions, and legacy_viewable_impressions are not necessarily integers, but floating numbers. This makes it possible to have rows with a small number of impressions and a low seen percentage.

Some fields are only available given certain conditions:

Field	Source: DSP (DV360)	Source: DSP (Xandr)	Source: DSP (Adform)	Source: DSP (Meta)	Source: Tracking Pixel
`"impressions"`	✅	✅	✅	✅	✅
`"seen_impressions"`	✅	✅	✅	✅	✅
`"benchmark_seen_impressions"`	✅	✅	✅	✅	✅
`"viewable_impressions"`	✅	✅	✅		✅
`"legacy_viewable_impressions"`					✅
`"clicks"`	✅	✅	✅	✅
`"conversions"`	✅	✅	✅
`"spend"`	✅	✅	✅	✅
`"calculated_spend"`	✅	✅	✅		✅

Public API

Authentication​

Conventions​

Errors​

Reference​

Base URL​

Endpoints​

GET /me​

GET /accounts​

Account​

GET /measurements​

Measurement​

GET /measurements/:id/creatives​

Creative​

GET /campaigns​

Campaign​

POST /campaigns/:campaignId/reports​

GET /campaigns/:campaignId/reports​

Report​

GET /reports/:id/rows​

ReportRow​

Dimensions​

Fields​