{ "openapi": "3.0.3", "info": { "version": "5.0.2", "title": "Pinterest REST API (Beta)", "description": "Pinterest's REST API", "contact": { "name": "Pinterest, Inc.", "url": "https://developers.pinterest.com/", "email": "pinterest-api@pinterest.com" }, "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "termsOfService": "https://developers.pinterest.com/terms/" }, "externalDocs": { "description": "Pinterest for Developers", "url": "https://developers.pinterest.com/" }, "servers": [ { "url": "https://api.pinterest.com/v5" } ], "tags": [ { "name": "ad_accounts", "description": "Interact with and view information about advertising." }, { "name": "boards", "description": "Interact with and view information about boards." }, { "name": "oauth", "description": "Generating and refreshing OAuth access tokens" }, { "name": "pins", "description": "Interact with and view information about Pins." }, { "name": "user_account", "description": "Read only information about user accounts associated with a given access token." } ], "paths": { "/oauth/token": { "post": { "summary": "Generate OAuth access token", "description": "Generate an OAuth access token by using an authorization code or a refresh token.", "tags": [ "oauth" ], "operationId": "oauth/token", "security": [ {} ], "requestBody": { "description": "Generate an OAuth access token.", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OauthAccessTokenRequest" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthAccessTokenResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account": { "get": { "summary": "Get user account", "description": "Get account information for the \"operation user_account\"\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".", "tags": [ "user_account" ], "operationId": "user_account/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "403": { "description": "Not authorized to access the user account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics": { "get": { "summary": "Get user account analytics", "description": "Get analytics for the \"operation user_account\"\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".", "tags": [ "user_account" ], "operationId": "user_account/analytics", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_from_claimed_content" }, { "$ref": "#/components/parameters/query_pin_format" }, { "$ref": "#/components/parameters/query_app_types" }, { "$ref": "#/components/parameters/query_metric_types" }, { "$ref": "#/components/parameters/query_split_field" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } }, "description": "Success" }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins": { "post": { "summary": "Create Pin", "description": "Create a Pin owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nNotes on the `POST /pins` function:\n\n1. This function is designed to create static Pins only - it is not currently possible to use this endpoint to create video Pins or Idea Pins.\n2. This function is intended solely for publishing new static content created by the user. If you are interested in saving images created by others to your Pinterest boards, sometimes called ‘curated content’, please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.", "tags": [ "pins" ], "operationId": "pins/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "requestBody": { "description": "Create a new Pin.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "400": { "description": "Pin is not a call-to-create response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Pin is not a call-to-create response" } } } }, "403": { "description": "The Pin's image is too small, too large or is broken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "The Pin's image is too small, too large or is broken" } } } }, "404": { "description": "Board, section or Pin not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board, section or Pin not found" } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 429, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}": { "get": { "summary": "Get Pin", "description": "Get a Pin owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.", "tags": [ "pins" ], "operationId": "pins/get", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access board or Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete Pin", "description": "Delete a Pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "pins" ], "operationId": "pins/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" } ], "responses": { "204": { "description": "Successfully deleted Pin" }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access board or Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}/analytics": { "get": { "summary": "Get Pin analytics", "description": "Get analytics for a Pin owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.", "tags": [ "pins" ], "operationId": "pins/analytics", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_app_types" }, { "$ref": "#/components/parameters/query_pin_analytics_metric_types" }, { "$ref": "#/components/parameters/query_split_field" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } } }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access board or Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards": { "get": { "summary": "List boards", "description": "Get a list of the boards owned by the \"operation user_account\" + group boards where this account is a collaborator\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Specify a privacy (from the types: public, protected, secret) to indicate which boards to return.\n- If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned.", "tags": [ "boards" ], "operationId": "boards/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "name": "privacy", "description": "Privacy setting for a board.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ] } } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Boards", "items": { "$ref": "#/components/schemas/Board" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create board", "description": "Create a board owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "requestBody": { "description": "Create a board using a single board json object.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "The board name is invalid or duplicated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "The board name is invalid or duplicated." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}": { "get": { "summary": "Get board", "description": "Get a board owned by the operation user_account - or a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/get", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update board", "description": "Update a board owned by the \"operating user_account\".\n- By default, the \"operating user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" } ], "requestBody": { "description": "Update a board.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardUpdate" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "Invalid board parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board parameters." } } } }, "403": { "description": "Not authorized to update the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to update the board." } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 429, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete board", "description": "Delete a board owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" } ], "responses": { "204": { "description": "Board deleted successfully" }, "403": { "description": "Not authorized to delete the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to delete the board." } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "429": { "description": "Could not get exclusive access to delete the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 429, "message": "Could not get exclusive access to delete the board." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections": { "get": { "summary": "List board sections", "description": "Get a list of all board sections from a board owned by the \"operation user_account\" - or a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Board sections", "items": { "$ref": "#/components/schemas/BoardSection" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create board section", "description": "Create a board section on a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" } ], "requestBody": { "description": "Create a board section.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "400": { "description": "Invalid board section parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board section parameters." } } } }, "403": { "description": "Not authorized to create board sections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to create board sections." } } } }, "409": { "description": "Could not get exclusive access to the board to create a new section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Could not get exclusive access to the board to create a new section." } } } }, "500": { "description": "Could not create a new board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 500, "message": "Could not create a new board section." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections/{section_id}": { "patch": { "summary": "Update board section", "description": "Update a board section on a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" } ], "requestBody": { "description": "Update a board section.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "400": { "description": "Invalid board section parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board section parameters." } } } }, "403": { "description": "Not authorized to update board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to update board section." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "summary": "Delete board section", "description": "Delete a board section on a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" } ], "responses": { "204": { "description": "Board section deleted successfully" }, "403": { "description": "Not authorized to delete board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to delete board section." } } } }, "404": { "description": "Board section not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board section not found." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections/{section_id}/pins": { "get": { "summary": "List Pins on board section", "description": "Get a list of the Pins on a board section of a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "403": { "description": "Not authorized to access Pins on board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access Pins on board section." } } } }, "404": { "description": "Board or section not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board or section not found." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/pins": { "get": { "summary": "List Pins on board", "description": "Get a list of the Pins on a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts": { "get": { "summary": "List ad accounts", "description": "Get a list of the ad_accounts that the \"operation user_account\" has access to.\n- This includes ad_accounts they own and ad_accounts that are owned by others who have granted them Business Access.", "tags": [ "ad_accounts" ], "operationId": "ad_accounts/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_include_shared_accounts" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Ad accounts", "items": { "$ref": "#/components/schemas/AdAccount" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/analytics": { "get": { "summary": "Get ad account analytics", "description": "Get analytics for the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "ad_account/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/campaigns": { "get": { "summary": "List campaigns", "description": "Get a list of the campaigns in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "campaigns/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account campaign parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account campaign parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/campaigns/analytics": { "get": { "summary": "Get campaign analytics", "description": "Get analytics for the specified campaigns in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "campaigns/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_campaign_ids_required" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account campaign analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account campaign analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/ad_groups": { "get": { "summary": "List ad groups", "description": "Get a list of the ad groups in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "ad_groups/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_ad_group_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_translate_interests_to_names" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account group parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account group parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/ad_groups/analytics": { "get": { "summary": "Get ad group analytics", "description": "Get analytics for the specified ad groups in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "ad_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_ad_group_ids_required" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account group analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account group analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/ads": { "get": { "summary": "List ads", "description": "Get a list of the ads in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "ads/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_ad_group_ids" }, { "$ref": "#/components/parameters/query_ad_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/ads/analytics": { "get": { "summary": "Get ad analytics", "description": "Get analytics for the specified ads in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "ads/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_ad_ids_required" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/product_groups/analytics": { "get": { "summary": "Get product group analytics", "description": "Get analytics for the specified product groups in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "product_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_product_group_ids_required" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } } }, "components": { "securitySchemes": { "pinterest_oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://www.pinterest.com/oauth/", "tokenUrl": "https://api.pinterest.com/v5/oauth/token", "scopes": { "ads:read": "See all of your advertising data", "boards:read": "See your public boards, including group boards you join", "boards:read_secret": "See your secret boards", "boards:write": "Create, update, or delete your public boards", "boards:write_secret": "Create, update, or delete your secret boards", "pins:read": "See your public Pins", "pins:read_secret": "See your secret Pins", "pins:write": "Create, update, or delete your public Pins", "pins:write_secret": "Create, update, or delete your secret Pins", "user_accounts:read": "See your user accounts" } } } }, "basic": { "type": "http", "scheme": "basic" } }, "schemas": { "Error": { "title": "Error", "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "Paginated": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "bookmark": { "type": "string", "nullable": true } }, "required": [ "items" ] }, "Account": { "type": "object", "readOnly": true, "properties": { "account_type": { "description": "Type of account", "type": "string", "enum": [ "PINNER", "BUSINESS" ] }, "profile_image": { "type": "string" }, "website_url": { "type": "string" }, "username": { "type": "string" } } }, "AnalyticsResponse": { "type": "object", "properties": { "all": { "type": "object", "properties": { "daily_metrics": { "description": "Daily metric array.", "items": { "type": "object", "properties": { "data_status": { "description": "Metrics availablity, e.g., \"READY\".", "example": "READY", "type": "string" }, "date": { "description": "Metrics date (UTC): YYYY-MM-DD.", "example": "2019-12-01", "type": "string" }, "metrics": { "description": "A dictionary of metrics and values.", "type": "object", "additionalProperties": { "type": "number" }, "example": { "ENGAGEMENT": 100, "CLICKTHROUGH_RATE": 0.2, "CLICKTHROUGH": 200, "CLOSEUP": 37, "CLOSEUP_RATE": 0.5, "ENGAGEMENT_RATE": 0.2, "SAVE": 20, "SAVE_RATE": 0.18, "IMPRESSION": 240 } } } }, "type": "array" }, "summary_metrics": { "description": "A dictionary of metrics and values.", "type": "object", "additionalProperties": { "type": "number" }, "example": { "ENGAGEMENT": 100, "CLICKTHROUGH_RATE": 0.2, "CLICKTHROUGH": 200, "CLOSEUP": 37, "CLOSEUP_RATE": 0.5, "ENGAGEMENT_RATE": 0.2, "SAVE": 20, "SAVE_RATE": 0.18, "IMPRESSION": 240 } } } } } }, "AdGroupSummaryStatus": { "type": "string", "description": "Summary status for ad group", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED" ] }, "AdResponse": { "allOf": [ { "type": "object", "description": "Creation fields", "properties": { "ad_group_id": { "description": "ID of the ad group that contains the ad.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "android_deep_link": { "description": "Deep link URL for Android devices. Not currently available. Using this field will generate an error.", "nullable": true, "type": "string" }, "carousel_android_deep_links": { "description": "Comma-separated deep links for the carousel pin on Android.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_destination_urls": { "description": "Comma-separated destination URLs for the carousel pin to promote.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_ios_deep_links": { "description": "Comma-separated deep links for the carousel pin on iOS.", "type": "array", "nullable": true, "items": { "type": "string" } }, "click_tracking_url": { "description": "Tracking url for the ad clicks.", "type": "string", "nullable": true }, "creative_type": { "description": "Ad creative type enum", "type": "string", "enum": [ "REGULAR", "VIDEO", "SHOPPING", "CAROUSEL", "MAX_VIDEO", "SHOP_THE_PIN", "STORY" ], "example": "REGULAR" }, "destination_url": { "description": "Destination URL.", "type": "string", "nullable": true }, "ios_deep_link": { "description": "Deep link URL for iOS devices. Not currently available. Using this field will generate an error.", "type": "string", "nullable": true }, "is_pin_deleted": { "description": "Is original pin deleted?", "example": false, "type": "boolean" }, "is_removable": { "description": "Is pin repinnable?", "example": false, "type": "boolean" }, "name": { "description": "Name of the ad - 255 chars max.", "type": "string", "nullable": true }, "pin_id": { "description": "Pin ID.", "example": "394205773611545468", "type": "string", "pattern": "^\\d+$" }, "status": { "$ref": "#/components/schemas/EntityStatus" }, "tracking_urls": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TrackingUrls" } ], "nullable": true }, "view_tracking_url": { "description": "Tracking URL for ad impressions.", "type": "string", "nullable": true } } }, { "type": "object", "properties": { "ad_account_id": { "description": "The ID of the advertiser that this ad belongs to.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" }, "campaign_id": { "description": "ID of the ad campaign that contains this ad.", "example": "626735565838", "type": "string", "pattern": "^\\d+$" }, "collection_items_destination_url_template": { "description": "Destination URL template for all items within a collections drawer.", "type": "string", "nullable": true }, "created_time": { "description": "Pin creation time. Unix timestamp in seconds.", "example": 1451431341, "type": "integer" }, "id": { "description": "The ID of this ad.", "example": "687195134316", "type": "string", "pattern": "^\\d+$" }, "rejected_reasons": { "description": "Enum reason why the pin was rejected. Returned if review_status is \"REJECTED\".", "type": "array", "items": { "type": "string", "description": "ad disapproval reasons", "enum": [ "HASHTAGS", "PROMOTIONS_AND_PRICES", "TARGETING", "LANDING_PAGE", "CAPS_AND_SYMBOLS", "SHOCKING", "WEIGHT_LOSS", "PROHIBITED_PRODUCT", "AUTHENTICITY", "NUDITY", "CONFUSING_DESIGN", "URGENCY", "RATINGS", "APP", "ALCOHOL", "CONTESTS", "POLITICAL", "OTHER", "IMAGE", "NAR", "INCONSISTENT", "CLICKBAIT", "NO_DESCRIPTION", "LOW_QUALITY", "EXAGGERATED_CLAIMS", "PINTEREST_BRAND", "ALCOHOL_NO_SALE", "LANDING_PAGE_SPEED", "LANDING_PAGE_HARDWALL", "LANDING_PAGE_BROKEN", "LANDING_PAGE_QUALITY", "OUT_OF_STOCK", "IMAGE_LOW_QUALITY", "IMAGE_BUSY", "IMAGE_POORLY_EDITED", "IMAGE_BEFORE_AFTER", "UGC", "FAKE_BUTTONS", "WEAPONS", "SENSITIVE", "UNACCEPTABLE_BUSINESS", "SUSPICIOUS_CLAIMS", "PHARMA", "SUSPICIOUS_SUPPLEMENTS", "ILLEGAL_RECREATIONAL_DRUG", "LOW_QUALITY_LANDING_PAGE", "RESTRICTED_HEALTHCARE", "INCONSISTENT_LANG_FR" ] } }, "rejection_labels": { "description": "Text reason why the pin was rejected. Returned if review_status is \"REJECTED\".", "type": "array", "items": { "type": "string" } }, "review_status": { "type": "string", "description": "Ad review status", "example": "PENDING", "enum": [ "OTHER", "PENDING", "REJECTED", "APPROVED" ] }, "type": { "description": "Always \"ad\".", "example": "pinpromotion", "type": "string" }, "updated_time": { "description": "Last update time. Unix timestamp in seconds.", "example": 1451431341, "type": "integer" }, "summary_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PinPromotionSummaryStatus" } ], "description": "Ad summary status" } } } ] }, "AdsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_ID": { "description": "The ID of the ad that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "AD_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "ActionType": { "type": "string", "description": "Ad group billable event type.", "example": "CLICKTHROUGH", "enum": [ "CLICKTHROUGH", "IMPRESSION", "VIDEO_V_50_MRC", "BILLABLE_ENGAGEMENT" ] }, "AdGroupResponse": { "allOf": [ { "type": "object", "properties": { "name": { "description": "Ad group name.", "type": "string", "example": "Ad Group For Pin: 687195905986" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ], "description": "Ad group/entity status." }, "budget_in_micro_currency": { "description": "Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups.", "type": "integer", "example": 5000000, "nullable": true }, "bid_in_micro_currency": { "description": "Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.", "type": "integer", "example": 5000000, "nullable": true }, "budget_type": { "description": "Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the end_time parameter is **REQUIRED**, and the ad group spend is spread evenly between the ad group `start_time` and `end_time` range. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome.", "type": "string", "enum": [ "DAILY", "LIFETIME", "CBO_ADGROUP" ] }, "start_time": { "description": "Ad group start time. Unix timestamp in seconds. Defaults to current time.", "type": "integer", "example": 5686848000, "nullable": true }, "end_time": { "description": "Ad group end time. Unix timestamp in seconds.", "type": "integer", "example": 5705424000, "nullable": true }, "targeting_spec": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Ad group targeting specification defining the ad group target audience. For example, '{\"APPTYPE\":[\"iphone\"], \"GENDER\":[\"male\"], \"LOCALE\":[\"en-US\"], \"LOCATION\":[\"501\"], \"AGE_BUCKET\":[\"25-34\"]}'" }, "lifetime_frequency_cap": { "description": "Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field **REQUIRES** the `end_time` field.", "type": "integer", "example": 100 }, "tracking_urls": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TrackingUrls" } ], "description": "Third-party tracking URLs.
JSON object with the format: {\"Tracking event enum\":[URL string array],...}
For example: {\"impression\": [\"URL1\", \"URL2\"], \"click\": [\"URL1\", \"URL2\", \"URL3\"]}.
Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. May be null. Pass in an empty object - {} - to remove tracking URLs.

For more information, see Third-party and dynamic tracking.", "nullable": true }, "auto_targeting_enabled": { "description": "Enable auto-targeting for ad group. Also known as \"expanded targeting\".", "type": "boolean", "example": true, "nullable": true }, "placement_group": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PlacementGroupType" } ], "description": "Placement group." }, "pacing_delivery_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PacingDeliveryType" } ], "description": "Pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a day." }, "conversion_learning_mode_type": { "type": "string", "description": "oCPM learn mode", "example": "ACTIVE", "nullable": true, "enum": [ "NOT_ACTIVE", "ACTIVE", null ] }, "summary_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/AdGroupSummaryStatus" } ], "description": "Ad group summary status." }, "feed_profile_id": { "description": "Feed Profile ID associated to the adgroup.", "type": "string", "example": "626736533506" } } }, { "type": "object", "properties": { "campaign_id": { "description": "Campaign ID of the ad group.", "type": "string", "pattern": "^\\d+$", "example": "626736533506" }, "billable_event": { "$ref": "#/components/schemas/ActionType" }, "id": { "description": "Ad group ID.", "type": "string", "pattern": "^\\d+$", "example": "2680060704746" }, "type": { "description": "Always \"adgroup\".", "type": "string" }, "ad_account_id": { "description": "Advertiser ID.", "type": "string", "pattern": "^\\d+$", "example": "549755885175" }, "created_time": { "description": "Ad group creation time. Unix timestamp in seconds.", "type": "integer", "example": 1476477189 }, "updated_time": { "description": "Ad group last update time. Unix timestamp in seconds.", "type": "integer", "example": 1476477189 } } } ] }, "AdGroupsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_GROUP_ID": { "description": "The ID of the ad group that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "AD_GROUP_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_GROUP_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "AdAccount": { "type": "object", "readOnly": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "title": "Ad account owner", "type": "object", "properties": { "username": { "type": "string", "description": "Public username for the user account" } } }, "country": { "type": "string", "description": "Country ID.", "example": "US", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "currency": { "type": "string", "description": "Currency Codes from ISO 4217", "example": "USD", "enum": [ "UNK", "USD", "GBP", "CAD", "EUR", "AUD", "NZD", "SEK", "ILS", "CHF", "HKD", "JPY", "SGD", "KRW", "NOK", "DKK", "PLN", "RON", "HUF", "CZK", "BRL", "MXN", "ARS", "CLP", "COP" ] } } }, "AdAccountAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_ACCOUNT_ID": { "description": "The ID of the advertiser that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "AD_ACCOUNT_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_ACCOUNT_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "Board": { "title": "Board", "description": "Board", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "549755885175" }, "name": { "type": "string", "example": "Summer Recipes" }, "description": { "type": "string", "nullable": true, "example": "My favorite summer recipes" }, "owner": { "allOf": [ { "$ref": "#/components/schemas/BoardOwner" } ], "type": "object", "readOnly": true }, "privacy": { "type": "string", "default": "PUBLIC", "description": "Privacy setting for a board. Learn more about secret boards and protected boards", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ] } }, "required": [ "name" ] }, "BoardOwner": { "title": "Board owner", "type": "object", "properties": { "username": { "type": "string", "readOnly": true } } }, "BoardSection": { "title": "Board section", "description": "Sections help organize pins within a board.", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "549755885175" }, "name": { "type": "string", "example": "Salads", "minLength": 1, "maxLength": 180 } } }, "BoardUpdate": { "title": "BoardUpdate", "description": "Board fields for updates", "type": "object", "properties": { "name": { "type": "string", "example": "Summer Recipes" }, "description": { "type": "string", "nullable": true, "example": "My favorite summer recipes" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "SECRET" ] } } }, "CampaignResponse": { "allOf": [ { "required": [ "id" ], "properties": { "id": { "description": "Campaign ID.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" } }, "type": "object" }, { "$ref": "#/components/schemas/CampaignCommon" }, { "type": "object", "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" }, "created_time": { "type": "integer", "description": "Campaign creation time. Unix timestamp in seconds.", "example": 1432744744 }, "updated_time": { "type": "integer", "description": "UTC timestamp. Last update time.", "example": 1432744744 }, "type": { "type": "string", "description": "Always \"campaign\".", "example": "campaign" } } } ] }, "CampaignsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "CAMPAIGN_ID": { "description": "The ID of the campaing that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "CAMPAIGN_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "CAMPAIGN_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "EntityStatus": { "type": "string", "description": "Entity status", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "OauthAccessTokenRequest": { "title": "OAuth access token request", "description": "Describes the valid schema for possible OAuth access token requests.", "type": "object", "discriminator": { "propertyName": "grant_type", "mapping": { "authorization_code": "#/components/schemas/OauthAccessTokenRequestCode", "refresh_token": "#/components/schemas/OauthAccessTokenRequestRefresh" } }, "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] } }, "required": [ "grant_type" ] }, "OauthAccessTokenRequestRefresh": { "title": "refresh_token", "description": "A request to exchange a refresh token for a new access token.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenRequest" }, { "type": "object", "properties": { "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "refresh_token" ] } ] }, "OauthAccessTokenRequestCode": { "title": "authorization_code", "description": "A request to exchange an authorization code for an access token.", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenRequest" }, { "type": "object", "properties": { "code": { "type": "string" }, "redirect_uri": { "type": "string" } }, "required": [ "code", "redirect_uri" ] } ] }, "OauthAccessTokenResponse": { "title": "OAuth access token response", "description": "A successful OAuth access token response.", "type": "object", "properties": { "response_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "access_token": { "type": "string" }, "token_type": { "type": "string", "default": "bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "discriminator": { "propertyName": "response_type", "mapping": { "authorization_code": "#/components/schemas/OauthAccessTokenResponseCode", "refresh_token": "#/components/schemas/OauthAccessTokenResponseRefresh" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "OauthAccessTokenResponseCode": { "title": "OAuth access token response", "description": "A successful OAuth access token response for the authorization code flow.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenResponse" }, { "type": "object", "properties": { "refresh_token": { "type": "string" }, "refresh_token_expires_in": { "type": "integer" } }, "required": [ "refresh_token", "refresh_token_expires_in" ] } ] }, "OauthAccessTokenResponseRefresh": { "title": "OAuth access token response", "description": "A successful OAuth access token response for the refresh token flow.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenResponse" } ] }, "OptimizationGoalMetadata": { "type": "object" }, "PacingDeliveryType": { "type": "string", "description": "Ad group pacing delivery type", "example": "STANDARD", "enum": [ "STANDARD", "ACCELERATED" ] }, "PlacementGroupType": { "type": "string", "description": "Campaign placement group type", "example": "ALL", "enum": [ "ALL", "SEARCH", "BROWSE", "OTHER" ] }, "Pin": { "title": "Pin", "description": "Pin", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "813744226420795884" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2020-01-01T20:10:40-00:00" }, "link": { "type": "string", "nullable": true, "example": "https://www.pinterest.com/" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "alt_text": { "type": "string", "nullable": true }, "board_id": { "description": "The board to which this Pin belongs.", "type": "string", "pattern": "\\d+" }, "board_section_id": { "description": "The board section to which this Pin belongs.", "type": "string", "pattern": "\\d+", "nullable": true }, "board_owner": { "allOf": [ { "$ref": "#/components/schemas/BoardOwner" } ], "type": "object", "readOnly": true }, "media": { "allOf": [ { "$ref": "#/components/schemas/PinMedia" } ], "type": "object", "readOnly": true }, "media_source": { "allOf": [ { "$ref": "#/components/schemas/PinMediaSource" } ], "type": "object", "writeOnly": true } } }, "PinMedia": { "title": "Pin media", "description": "Pin media objects.", "discriminator": { "propertyName": "media_type", "mapping": { "image": "#/components/schemas/PinMediaWithImage" } }, "properties": { "media_type": { "type": "string" } } }, "PinMediaWithImage": { "title": "image", "description": "Pin with image.", "allOf": [ { "type": "object", "properties": { "images": { "type": "object", "additionalProperties": { "title": "ImageDetails", "type": "object", "properties": { "width": { "type": "integer", "minimum": 100 }, "height": { "type": "integer", "minimum": 100, "nullable": true }, "url": { "type": "string" } }, "required": [ "height", "width", "url" ], "example": { "width": 400, "height": 300, "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" } } } } }, { "$ref": "#/components/schemas/PinMedia" } ], "example": { "media_type": "image", "images": { "400x300": { "width": 400, "height": 300, "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "600x": { "width": 600, "height": 600, "url": "https://i.pinimg.com/600x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "orig": { "width": 560, "height": 560, "url": "https://i.pinimg.com/originals/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" } } } }, "PinMediaSource": { "title": "Pin media source", "description": "Pin media source.", "discriminator": { "propertyName": "source_type", "mapping": { "image_base64": "#/components/schemas/PinMediaSourceImageBase64", "image_url": "#/components/schemas/PinMediaSourceImageURL" } }, "properties": { "source_type": { "type": "string" } }, "required": [ "source_type" ] }, "PinMediaSourceImageBase64": { "title": "Image Base64", "description": "Base64-encoded image media source", "allOf": [ { "$ref": "#/components/schemas/PinMediaSource" }, { "type": "object", "properties": { "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png" ] }, "data": { "type": "string", "pattern": "[a-zA-Z0-9+\\/=]+" } }, "required": [ "content_type", "data" ] } ] }, "PinMediaSourceImageURL": { "title": "Image URL", "description": "Image URL-based media source", "allOf": [ { "$ref": "#/components/schemas/PinMediaSource" }, { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } ] }, "PinPromotionSummaryStatus": { "type": "string", "description": "Summary status for pin promotions", "example": "APPROVED", "enum": [ "APPROVED", "PAUSED", "PENDING", "REJECTED", "ADVERTISER_DISABLED", "ARCHIVED" ] }, "ProductGroupAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "PRODUCT_GROUP_ID": { "description": "The ID of the product group that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "PRODUCT_GROUP_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "PRODUCT_GROUP_ID": "74629351736530", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "CampaignCommon": { "required": [ "ad_account_id" ], "type": "object", "description": "Campaign Data", "properties": { "ad_account_id": { "description": "Campaign's Advertiser ID.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Campaign name.", "example": "ACME Tools" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ], "default": "ACTIVE" }, "lifetime_spend_cap": { "description": "Campaign total spending cap.", "example": 1432744744, "type": "integer", "nullable": true }, "daily_spend_cap": { "description": "Campaign daily spending cap.", "example": 1432744744, "type": "integer", "nullable": true }, "order_line_id": { "description": "Order line ID that appears on the invoice.", "example": "549755885175", "type": "string", "pattern": "^\\d+$", "nullable": true }, "tracking_urls": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackingUrls" } ] } } }, "ObjectiveType": { "type": "string", "description": "Campaign objective type.", "enum": [ "AWARENESS", "CONSIDERATION", "VIDEO_VIEW", "WEB_CONVERSION", "CATALOG_SALES", "WEB_SESSIONS", "AWARENESS_RESERVED", "ENGAGEMENT" ] }, "TrackingUrls": { "description": "Third-party tracking URLs. Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see Third-party and dynamic tracking.", "example": { "impression": [ "URL1", "URL2" ], "click": [ "URL1", "URL2" ], "engagement": [ "URL1", "URL2" ], "buyable_button": [ "URL1", "URL2" ], "audience_verification": [ "URL1", "URL2" ] }, "type": "object", "nullable": true, "properties": { "impression": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "click": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "engagement": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "buyable_button": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "audience_verification": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 } } }, "CampaignSummaryStatus": { "type": "string", "description": "Summary status for campaign", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED" ] } }, "parameters": { "path_ad_account_id": { "name": "ad_account_id", "description": "Unique identifier of an ad account.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_board_id": { "name": "board_id", "description": "Unique identifier of a board.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_board_section_id": { "name": "section_id", "description": "Unique identifier of a board section.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_pin_id": { "name": "pin_id", "description": "Unique identifier of a Pin.", "in": "path", "required": true, "schema": { "type": "string" } }, "query_ad_account_id": { "name": "ad_account_id", "description": "Unique identifier of an ad account.", "in": "query", "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_ad_group_ids": { "description": "List of Ad group Ids.", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_group_ids_required": { "description": "List of Ad group Ids.", "in": "query", "name": "ad_group_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_ids": { "description": "List of Ad Ids.", "in": "query", "name": "ad_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_ids_required": { "description": "List of Ad Ids.", "in": "query", "name": "ad_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_app_types": { "description": "Apps or devices to get data for, default is all.", "in": "query", "name": "app_types", "required": false, "schema": { "default": "ALL", "enum": [ "ALL", "MOBILE", "TABLET", "WEB" ], "type": "string" } }, "query_bookmark": { "name": "bookmark", "description": "Cursor used to fetch the next page of items", "in": "query", "required": false, "schema": { "type": "string" } }, "query_campaign_ids": { "description": "List of Campaign Ids.", "in": "query", "name": "campaign_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_campaign_ids_required": { "description": "List of Campaign Ids.", "in": "query", "name": "campaign_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_columns": { "description": "Columns to retrieve. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD, it's microdollars. Otherwise, it's in microunits of the advertiser's currency.
For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits.
If a column has no value, it may not be returned", "explode": false, "in": "query", "name": "columns", "required": true, "schema": { "items": { "type": "string", "description": "Reporting columns", "example": "SPEND_IN_DOLLAR", "enum": [ "AD_ACCOUNT_ID", "AD_GROUP_ENTITY_STATUS", "AD_GROUP_ID", "AD_ID", "CAMPAIGN_DAILY_SPEND_CAP", "CAMPAIGN_ENTITY_STATUS", "CAMPAIGN_ID", "CAMPAIGN_LIFETIME_SPEND_CAP", "CAMPAIGN_NAME", "CHECKOUT_ROAS", "CLICKTHROUGH_1", "CLICKTHROUGH_1_GROSS", "CLICKTHROUGH_2", "CPC_IN_MICRO_DOLLAR", "CPM_IN_DOLLAR", "CPM_IN_MICRO_DOLLAR", "CTR", "CTR_2", "ECPCV_IN_DOLLAR", "ECPCV_P95_IN_DOLLAR", "ECPC_IN_DOLLAR", "ECPC_IN_MICRO_DOLLAR", "ECPE_IN_DOLLAR", "ECPM_IN_MICRO_DOLLAR", "ECPV_IN_DOLLAR", "ECTR", "EENGAGEMENT_RATE", "ENGAGEMENT_1", "ENGAGEMENT_2", "ENGAGEMENT_RATE", "IDEA_PIN_PRODUCT_TAG_VISIT_1", "IDEA_PIN_PRODUCT_TAG_VISIT_2", "IMPRESSION_1", "IMPRESSION_1_GROSS", "IMPRESSION_2", "INAPP_CHECKOUT_COST_PER_ACTION", "OUTBOUND_CLICK_1", "OUTBOUND_CLICK_2", "PAGE_VISIT_COST_PER_ACTION", "PAGE_VISIT_ROAS", "PAID_IMPRESSION", "PIN_ID", "REPIN_1", "REPIN_2", "REPIN_RATE", "SPEND_IN_DOLLAR", "SPEND_IN_MICRO_DOLLAR", "TOTAL_CHECKOUT", "TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICKTHROUGH", "TOTAL_CLICK_CHECKOUT", "TOTAL_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_SIGNUP", "TOTAL_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_CONVERSIONS", "TOTAL_CUSTOM", "TOTAL_ENGAGEMENT", "TOTAL_ENGAGEMENT_CHECKOUT", "TOTAL_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_SIGNUP", "TOTAL_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_IDEA_PIN_PRODUCT_TAG_VISIT", "TOTAL_IMPRESSION_FREQUENCY", "TOTAL_IMPRESSION_USER", "TOTAL_LEAD", "TOTAL_PAGE_VISIT", "TOTAL_REPIN_RATE", "TOTAL_SIGNUP", "TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIDEO_3SEC_VIEWS", "TOTAL_VIDEO_AVG_WATCHTIME_IN_SECOND", "TOTAL_VIDEO_MRC_VIEWS", "TOTAL_VIDEO_P0_COMBINED", "TOTAL_VIDEO_P100_COMPLETE", "TOTAL_VIDEO_P25_COMBINED", "TOTAL_VIDEO_P50_COMBINED", "TOTAL_VIDEO_P75_COMBINED", "TOTAL_VIDEO_P95_COMBINED", "TOTAL_VIEW_CHECKOUT", "TOTAL_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_SIGNUP", "TOTAL_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CHECKOUT", "TOTAL_WEB_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_CHECKOUT", "TOTAL_WEB_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_CHECKOUT", "TOTAL_WEB_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_CHECKOUT", "TOTAL_WEB_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "VIDEO_3SEC_VIEWS_2", "VIDEO_LENGTH", "VIDEO_MRC_VIEWS_2", "VIDEO_P0_COMBINED_2", "VIDEO_P100_COMPLETE_2", "VIDEO_P25_COMBINED_2", "VIDEO_P50_COMBINED_2", "VIDEO_P75_COMBINED_2", "VIDEO_P95_COMBINED_2", "WEB_CHECKOUT_COST_PER_ACTION", "WEB_CHECKOUT_ROAS" ] }, "type": "array" } }, "query_conversion_attribution_click_window_days": { "name": "click_window_days", "in": "query", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 30 }, "description": "Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.", "example": 1 }, "query_conversion_attribution_engagement_window_days": { "name": "engagement_window_days", "in": "query", "description": "Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 30 } }, "query_conversion_attribution_view_window_days": { "name": "view_window_days", "in": "query", "description": "Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 1 } }, "query_conversion_attribution_conversion_report_time": { "description": "The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.", "example": "TIME_OF_AD_ACTION", "in": "query", "name": "conversion_report_time", "schema": { "type": "string", "enum": [ "TIME_OF_AD_ACTION", "TIME_OF_CONVERSION" ], "default": "TIME_OF_AD_ACTION" } }, "query_downstream": { "description": "Include downstream metrics? Default is 0 (false).", "in": "query", "name": "downstream", "required": false, "schema": { "default": 0, "enum": [ 0, 1, 2 ], "type": "integer" } }, "query_end_date": { "description": "Metric report end date (UTC). Format: YYYY-MM-DD", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string", "format": "date" } }, "query_entity_statuses": { "in": "query", "name": "entity_statuses", "required": false, "description": "Entity status", "schema": { "type": "array", "items": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] } } }, "query_from_claimed_content": { "description": "Filter on Pins that match your claimed domain.", "in": "query", "name": "from_claimed_content", "required": false, "schema": { "default": "BOTH", "enum": [ "OTHER", "CLAIMED", "BOTH" ], "type": "string" } }, "query_granularity": { "description": "Granularity", "example": "DAY", "in": "query", "name": "granularity", "required": true, "schema": { "type": "string", "enum": [ "TOTAL", "DAY", "HOUR", "WEEK", "MONTH" ] } }, "query_metric_types": { "description": "Metric types to get data for, default is all. ", "explode": false, "in": "query", "name": "metric_types", "required": false, "schema": { "items": { "enum": [ "ENGAGEMENT", "ENGAGEMENT_RATE", "IMPRESSION", "OUTBOUND_CLICK", "OUTBOUND_CLICK_RATE", "PIN_CLICK", "PIN_CLICK_RATE", "SAVE", "SAVE_RATE" ], "type": "string" }, "type": "array" }, "style": "form" }, "query_pin_analytics_metric_types": { "description": "Pin metric types to get data for, default is all.", "explode": false, "in": "query", "name": "metric_types", "required": true, "schema": { "items": { "enum": [ "IMPRESSION", "SAVE", "PIN_CLICK", "OUTBOUND_CLICK", "VIDEO_MRC_VIEW", "VIDEO_AVG_WATCH_TIME", "VIDEO_V50_WATCH_TIME", "QUARTILE_95_PERCENT_VIEW" ], "type": "string" }, "type": "array" }, "style": "form" }, "query_owned_content_list": { "description": "Get metrics for domains or owned accounts, default is all. ", "explode": false, "in": "query", "name": "owned_content_list", "required": false, "schema": { "items": { "type": "string" }, "type": "array" }, "style": "form" }, "query_split_field": { "description": "How to split the data into groups. Not including this param means data won't be split.", "required": false, "in": "query", "explode": false, "name": "split_field", "schema": { "default": "NO_SPLIT", "enum": [ "NO_SPLIT", "APP_TYPE", "CONTENT_TYPE", "OWNED_CONTENT", "SOURCE", "PIN_FORMAT", "CONVERSION_TYPE", "ATTRIBUTION_EVENT" ], "type": "string" } }, "query_order": { "description": "The order in which to sort the items returned: “ASCENDING” or “DESCENDING”\nby ID. Note that higher-value IDs are associated with more-recently added\nitems.", "in": "query", "name": "order", "required": false, "schema": { "type": "string", "example": "ASCENDING", "enum": [ "ASCENDING", "DESCENDING" ] } }, "query_page_size": { "name": "page_size", "description": "Maximum number of items to include in the response.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "query_pin_format": { "description": "Pin formats to get data for, default is all.", "in": "query", "name": "pin_format", "required": false, "schema": { "default": "ALL", "enum": [ "ALL", "PRODUCT", "REGULAR", "VIDEO" ], "type": "string" } }, "query_product_group_ids_required": { "description": "List of Product group Ids.", "in": "query", "name": "product_group_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_start_date": { "description": "Metric report start date (UTC). Format: YYYY-MM-DD", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string", "format": "date" } }, "query_include_shared_accounts": { "in": "query", "description": "Include shared ad accounts", "name": "include_shared_accounts", "required": false, "schema": { "type": "boolean", "default": true } }, "query_translate_interests_to_names": { "description": "Return interests as text names and not topic IDs?", "in": "query", "name": "translate_interests_to_names", "required": false, "schema": { "type": "boolean", "default": false } } } } }