Complete statistics for each level of campaign

This report provides an overview of campaign statistics, including the number of contacted prospects, response rate, bounce rate, interest levels, and more. It focuses on step-level metrics. For detailed statistics at campaign-level, please refer to the General statistics per campaign report.

The statistics are grouped by campaign, campaign step, and step's A/B version.
Campaigns with YES/NO paths have the results aggregated per step, not per path.
Campaigns and campaign steps that did not send any messages during the selected period will not be included in the results.

You can preview example results below

Generating a report

Use the below endpoint to generate a report hash. Afterwards use the rest/v2/reports/{hash} to retrieve the statistics data.

Request

Endpoint

POST https://api.woodpecker.co/rest/v2/reports/complete_statistics_for_each_level_of_campaign

Headers

x-api-key: {YOUR_API_KEY}
Content-type: application/json

For details on how to authenticate your requests, please see the authentication guide.

Body

A JSON object containing from and to date fields, that define the date period for the report's data generation.

info

You can generate data for up to 30 last days

{
  "from": "YYYY-MM-DD",
  "to": "YYYY-MM-DD"
}

Field	Type	Description	Example
`from`	string	Start date of the report in ISO 8601 format	`"2025-01-01"`
`to`	string	End date of the report in ISO 8601 format	`"2025-01-31"`

Request sample

Generate a report hash

cURL
Java
Node.js

curl --request POST \
  --url "https://api.woodpecker.co/rest/v2/reports/complete_statistics_for_each_level_of_campaign" \
  --header "Content-Type: application/json" \
  --header "x-api-key: {YOUR_API_KEY}" \
  --data '{
    "from": "YYYY-MM-DD",
    "to": "YYYY-MM-DD"
  }'

import com.fasterxml.jackson.databind.ObjectMapper;

public class WoodpeckerApiClient {
  public static String sendReportRequest(String apiKey, String fromDate, String toDate) throws Exception {
    HttpClient client = HttpClient.newHttpClient();
    ObjectMapper objectMapper = new ObjectMapper();

    Map<String, String> requestBody = Map.of(
      "from", fromDate,
      "to", toDate
    );

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("https://api.woodpecker.co/rest/v2/reports/complete_statistics_for_each_level_of_campaign"))
      .header("Content-Type", "application/json")
      .header("x-api-key", apiKey)
      .POST(HttpRequest.BodyPublishers.ofString(objectMapper.writeValueAsString(requestBody)))
      .build();

    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    Map<String, String> responseBody = objectMapper.readValue(response.body(), Map.class);
    return responseBody.get("hash");
  }
}

const axios = require("axios");

async function sendReportRequest(apiKey, fromDate, toDate) {
  try {
    const response = await axios.post(
      "https://api.woodpecker.co/rest/v2/reports/complete_statistics_for_each_level_of_campaign",
      {
        from: fromDate,
        to: toDate,
      },
      {
        headers: {
          "Content-Type": "application/json",
          "x-api-key": apiKey,
        },
      }
    );

    return response.data.hash;
  } catch (error) {
    console.error("Error making API request:", error);
    throw error;
  }
}

const apiKey = "YOUR_API_KEY";
const fromDate = "YYYY-MM-DD";
const toDate = "YYYY-MM-DD";

sendReportRequest(apiKey, fromDate, toDate)
  .then((hash) => console.log("Report hash:", hash))
  .catch((error) => console.error(error));

Response

Response examples

The response is a hash that you should use the fetch the report content using the rest/v2/reports/{hash} endpoint.

{
  "hash":"c966572e5b7c12d73f....347b5186242782c9550d"
}

Body schema

Field	Type	Description
`hash`	string	Representation of the report's ID. Use it to fetch the generated data

Invalid request parameters or malformed request syntax. Please review the request body

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Reports can be generated from the last 30 days. Change the from parameter" | "Value of to is incorrect." | "Value of from is incorrect." | "From date cannot be later than the to date.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Please review the request URL

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Incorrect report name in the URL. Please review the endpoint URL

Status: 405
Body: None

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Retrieving a report

After requesting the report generation, you can fetch it using the below endpoint. Insert the hash, obtained from the above request, to the URL.

Preparing the data may take some time. Please check the status value to monitor the progress. The possible statuses are PENDING, WAITING, IN_PROGRESS, READY and FAILED.

Request

Endpoint

GET https://api.woodpecker.co/rest/v2/reports/{hash}

Headers

x-api-key: {YOUR_API_KEY}

For details on how to authenticate your requests, please see the authentication guide.

Request sample

Retrieve a report using the hash

cURL
Java
Node.js

curl --request GET \
  --url "https://api.woodpecker.co/rest/v2/reports/{hash}" \
  --header "x-api-key: {YOUR_API_KEY}"

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URL;

public class WoodpeckerApiClient {
  public static void main(String[] args) {
    String apiKey = "YOUR_API_KEY"; // Replace with your actual API key
    String hash = "YOUR_REPORT_HASH"; // Replace with the actual hash
    String endpoint = "https://api.woodpecker.co/rest/v2/reports/" + hash;

    try {
      URL url = new URL(endpoint);
      HttpURLConnection connection = (HttpURLConnection) url.openConnection();
      connection.setRequestMethod("GET");
      connection.setRequestProperty("x-api-key", apiKey);

      int responseCode = connection.getResponseCode();
      if (responseCode == HttpURLConnection.HTTP_OK) {
        BufferedReader in = new BufferedReader(new InputStreamReader(connection.getInputStream()));
        String inputLine;
        StringBuilder response = new StringBuilder();

        while ((inputLine = in.readLine()) != null) {
          response.append(inputLine);
        }
        in.close();

        System.out.println("Response: " + response.toString());
      } else {
        System.out.println("GET request failed with response code: " + responseCode);
      }

      connection.disconnect();
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

const axios = require("axios");

const apiKey = "YOUR_API_KEY";
const hash = "YOUR_REPORT_HASH";
const url = `https://api.woodpecker.co/rest/v2/reports/${hash}`;

axios
  .get(url, {
    headers: {
      "x-api-key": apiKey,
    },
  })
  .then((response) => {
    console.log("Response:", response.data);
  })
  .catch((error) => {
    console.error("Error:", error.response ? error.response.data : error.message);
  });

Response

Response examples

This example presents campaign statistics for the period from January 1 to January 31, 2025, covering two campaigns. You can observe ten objects as both campaigns utilize three A/B/C versions of the first step and one version for steps two and three.

Successful response example

{
  "status": "READY",
  "report": {
    "description": "Complete_statistics_for_each_level_of_campaign_2025-01-01-2025-01-31",
    "data": [
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 1234567,
        "name": "First successful campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "A",
        "sent": 75,
        "bounced": 1,
        "bounce_rate": 1.3,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 74,
        "responded": 4,
        "responded_rate": 5.4,
        "interested_yes": 2,
        "interested_maybe": 0,
        "interested_no": 2
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 1234567,
        "name": "First successful campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "B",
        "sent": 76,
        "bounced": 1,
        "bounce_rate": 1.3,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 75,
        "responded": 4,
        "responded_rate": 5.3,
        "interested_yes": 1,
        "interested_maybe": 0,
        "interested_no": 3
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 1234567,
        "name": "First successful campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "C",
        "sent": 78,
        "bounced": 2,
        "bounce_rate": 2.6,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 76,
        "responded": 3,
        "responded_rate": 3.9,
        "interested_yes": 1,
        "interested_maybe": 0,
        "interested_no": 2
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 1234567,
        "name": "First successful campaign",
        "campaign_status": "RUNNING",
        "step": 2,
        "version": "A",
        "sent": 201,
        "bounced": 1,
        "bounce_rate": 0.5,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 200,
        "responded": 10,
        "responded_rate": 5.0,
        "interested_yes": 0,
        "interested_maybe": 3,
        "interested_no": 5
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 1234567,
        "name": "First successful campaign",
        "campaign_status": "RUNNING",
        "step": 3,
        "version": "A",
        "sent": 177,
        "bounced": 0,
        "bounce_rate": 0.0,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 177,
        "responded": 3,
        "responded_rate": 1.7,
        "interested_yes": 0,
        "interested_maybe": 0,
        "interested_no": 3
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 9876543,
        "name": "Second campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "A",
        "sent": 34,
        "bounced": 1,
        "bounce_rate": 2.9,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 33,
        "responded": 0,
        "responded_rate": 0.0,
        "interested_yes": 0,
        "interested_maybe": 0,
        "interested_no": 0
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 9876543,
        "name": "Second campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "B",
        "sent": 32,
        "bounced": 1,
        "bounce_rate": 3.1,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 31,
        "responded": 3,
        "responded_rate": 9.7,
        "interested_yes": 0,
        "interested_maybe": 1,
        "interested_no": 2
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 9876543,
        "name": "Second campaign",
        "campaign_status": "RUNNING",
        "step": 1,
        "version": "C",
        "sent": 31,
        "bounced": 0,
        "bounce_rate": 0.0,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 31,
        "responded": 1,
        "responded_rate": 3.2,
        "interested_yes": 0,
        "interested_maybe": 0,
        "interested_no": 1
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 9876543,
        "name": "Second campaign",
        "campaign_status": "RUNNING",
        "step": 2,
        "version": "A",
        "sent": 89,
        "bounced": 0,
        "bounce_rate": 0.0,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 89,
        "responded": 4,
        "responded_rate": 4.5,
        "interested_yes": 0,
        "interested_maybe": 1,
        "interested_no": 3
      },
      {
        "client": "Bachmanity",
        "campaign_owner": "Erlich",
        "id": 9876543,
        "name": "Second campaign",
        "campaign_status": "RUNNING",
        "step": 3,
        "version": "A",
        "sent": 69,
        "bounced": 0,
        "bounce_rate": 0.0,
        "opened": 0,
        "opened_rate": 0.0,
        "clicked": 0,
        "opt_out": 0,
        "opt_out_rate": 0.0,
        "delivered": 69,
        "responded": 1,
        "responded_rate": 1.4,
        "interested_yes": 0,
        "interested_maybe": 0,
        "interested_no": 1
      }
    ]
  }
}

Body schema

Field	Type	Description
`status`	string	Status of the generation. `PENDING`, `WAITING`, `IN_PROGRESS`, `READY`, `FAILED`
`report`	object/null	Container for report details. Null if `status` is not `READY`
└─`report.description`	string	Full name of the report and its period
└─`report.data`	array	List of campaign statistics
└─`data[].client`	string	Name of the Woodpecker account
└─`data[].campaign_owner`	string	Full name of the Woodpecker user who created the campaign
└─`data[].id`	integer	Unique ID of the campaign
└─`data[].name`	string	Name of the campaign
└─`data[].campaign_status`	string	Current status of the campaign. One of: `RUNNING` `PAUSED` `STOPPED` `EDITED` `DRAFT` `COMPLETED` `DELETED`
└─`data[].step`	integer	Step of the campaign
└─`data[].version`	string	A/B/C/D/E version of of a step
└─`data[].sent`	integer	Number of contacted prospects
└─`data[].bounced`	integer	Number of prospects who bounced
└─`data[].bounce_rate`	string	Percentage of prospects who bounced
└─`data[].opened`	integer	Number of prospects who opened an email
└─`data[].opened_rate`	string	Percentage of prospects who opened an email
└─`data[].clicked`	integer	Number of prospects who who clicked a link
└─`data[].opt_out`	integer	Number of prospects who opted-out
└─`data[].opt_out_rate`	integer	Percentage of prospects who opted-out
└─`data[].delivered`	integer	Number of prospects who received an email
└─`data[].responded`	integer	Number of prospects who responded
└─`data[].responded_rate`	string	Percentage of prospects who responded
└─`data[].interested_yes`	integer	Number of "interested" responses
└─`data[].interested_maybe`	integer	Number of "maybe later" responses
└─`data[].interested_no`	integer	Number of "not interested" responses

An issue with authorization. Please review the authorization guide

{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid api key",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Report not found - please check the hash or the request URL.

{
  "title": "Not Found",
  "status": 404,
  "detail": "Requested resource does not exist",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Unknown error, please try again later

{
  "title": "Internal server error",
  "status": 500,
  "detail": "An unexpected error has occurred. Please try again later.",
  "timestamp": "2025-03-05 17:57:00"
}

Body schema

Field	Type	Description
`title`	string	A short title describing the error
`status`	integer	The HTTP status code
`detail`	string	A detailed message explaining the error
`timestamp`	string	The timestamp when the error occurred, `YYYY-MM-DD HH:MM:SS` UTC

Generating a report​

Request​

Endpoint​

Headers​

Body​

Request sample​

Generate a report hash​

Response​

Response examples​

Body schema​

Body schema​

Body schema​

Body schema​

Body schema​

Retrieving a report​

Request​

Endpoint​

Headers​

Request sample​

Retrieve a report using the hash​

Response​

Response examples​

Body schema​

Body schema​

Body schema​

Body schema​

Generating a report

Request

Endpoint

Headers

Body

Request sample

Generate a report hash

Response

Response examples

Body schema

Body schema

Body schema

Body schema

Body schema

Retrieving a report

Request

Endpoint

Headers

Request sample

Retrieve a report using the hash

Response

Response examples

Body schema

Body schema

Body schema

Body schema