Known agents

A known agent deterministically identifies and describes each participant in the marketplace, including the buying and selling parties in a deal. The Trade Desk assigns each participant a known agent ID (KAID) during onboarding. This unique ID is then used to look up their information such as known agent type and account preferences. If you're a seller, you can also access known agent ownership information—publishers owned by a seller, or advertisers listed under an agency.

As a selling party, you can run known agent queries to gather participant-specific information necessary for creating and managing deals. For example, to initiate a deal, you must identify yourself as the selling party and search for a prospective buying party, as described in Get started with the PDP API for selling parties.

The following diagram outlines how selling parties and The Trade Desk use known agent identifiers.

Here's what you need to know about known agents:

You must include a KAID to identify buying and selling parties when creating deals.
To access a known agent, you must have permission from the owner.
You can view the known agent of any party that has transacted inventory through your deals.
If you have access to a seller or agency, you can also access the known agents of their associated publishers or advertisers.
All known agent objects are read-only.

Types of known agents

The Trade Desk assigns the known agent type during onboarding. The following table outlines the types of known agents supported by the PDP API. For field details, see Known Agent object.

Type	Description
Seller	An entity that owns one or more publishers, and sells inventory created by those publishers. Seller IDs are typically sourced from the `sellers.json` file. NOTE: Under limited circumstances, a classified seller might also resell small amounts of inventory owned by another seller.
Publisher	A content owner whose content or inventory is available for sale by a seller. The PDP API maps publishers using information found in the `ads.txt` file, with additional curation from The Trade Desk.
Intermediary	An entity, such as an SSP, that facilitates ad inventory distribution but doesn't own inventory.
Agency	An advertising agency that buys ad inventory on behalf of a brand. NOTE: Under limited circumstances, a classified seller might also be an agency.
Advertiser	A brand that acquires inventory through The Trade Desk platform.

Known agent queries

Known agent object queries enable you to search for a buying party, determine your account classification for deal initiation, or look up relevant information about deal participants. For field details, see Known Agent object.

IMPORTANT: If a buying party has opted out of sharing its KAID through the Provisioning API, contact them directly.

To query for known agents, you must have the following:

Your account ID assigned during onboarding.
Access to the owner's known agent.

TIP: In some cases, a KAID is inactive or no longer in use. Check for active known agents by including the isEnabled field in your queries.

Look up your account known agent

The following knownAgentOfAccount query retrieves the known agent details associated with your account.

query GetKnownAgentOfAccount {
  knownAgentOfAccount(input: { accountId: "ACCOUNT_ID_PLACEHOLDER" }) {
    id
    name
    type
    isEnabled
  }
}

Look up known agents by type

The following knownAgents query retrieves the known agent information of agencies that have granted you permission to access their known agent. To query other types of known agents, replace the AGENCY value with a different type. For field details, see Known Agent object.

query GetAgencyKnownAgentExample {
  knownAgents(
    where: { 
      accountId: { in: ["ACCOUNT_ID_PLACEHOLDER"] }
      type: { in: [AGENCY] }
    }
  ) {
    totalCount
    nodes {
      id
      name
      isEnabled
    }
  }
}

Look up known agents by KAID

The following knownAgents query retrieves known agents using the KAID.

query GetKnownAgentByIdExample {
  knownAgents(
    where: { 
      accountId: { in: ["ACCOUNT_ID_PLACEHOLDER"] }
      id: { in: ["KNOWN_AGENT_ID_PLACEHOLDER"] }
    }
  ) {
    totalCount
    nodes {
      id
      name
      isEnabled
    }
  }
}

Look up known agents by domain

To search for known agents by domain, use the search filter and pass in the domain name or URL. The currently active seller domain is returned in the domain field.

TIP: To retrieve a historical record of all other domains previously associated with the seller, query the additionalDomains field in the KnownAgentSeller object.

The following knownAgents query retrieves all domains under a selling party.

query KnownAgents {
    knownAgents(
        where: {
            accountId: { in: ["ACCOUNT_ID_PLACEHOLDER"] }
            search: { contains: "DOMAIN_NAME_PLACEHOLDER" }
            type: { in: [SELLER] }
        }
    ) {
        nodes {
            id
            name
            type
            ... on KnownAgentSeller {
                domain
                additionalDomains
                isEnabled
                publishers {
                    nodes {
                        id
                        name
                    }
                    totalCount
                }
            }
        }
    }
}

Look up advertisers that belong to an agency

To search for relationships between known agent types, use the parentKnownAgentId. The following knownAgents query retrieves all advertiser known agents that are under an agency.

query GetAgencyAdvertisersExample {
  knownAgents(
    where: { 
      accountId: { in: ["ACCOUNT_ID_PLACEHOLDER"] }
      parentKnownAgentId: { in: ["AGENCY_KNOWN_AGENT_ID_PLACEHOLDER"] }
      type: { in: [ADVERTISER] }
    }
  ) {
    totalCount
    nodes {
      id
      name
      isEnabled
    }
  }
}

Look up mappings for an account

The mapping uses the relationship between a known agent with seller information found in their sellers.json file. The following sellersJsonMappingsForAccount query returns the mapping for an account.

query GetMappingsForAccountExample {
  sellersJsonMappingsForAccount(
    input: { accountId: "ACCOUNT_ID_PLACEHOLDER"}
    ) {
    nodes {
      sellerId
      name
      domain
      knownAgent {
        id
        name
        isEnabled
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

FAQs

The following is a list of commonly asked questions about known agent access.

Can I edit the details of a known agent?

No. The known agent object is read-only.

Can other users access my information in the known agent object?

Sellers have access to known agents that they own or manage, as defined in their ads.txt.

What buying parties appear when I query for a known agent object?

When you query for a KAID, the Provisioning endpoint returns a list of related advertisers and agencies involved in your deals. Deals can grant access to known agents listed with a seat ID for each agency, or the aadv field for additional advertisers.

IMPORTANT: To access advertisers under an agency, you must also have permission to access the agency's known agent.