> For a complete page index, fetch https://developer.close.com/llms.txt

# Get a funnel report (stages)

POST https://api.close.com/api/v1/report/funnel/opportunity/stages/
Content-Type: application/json

The opportunity funnel "stages" report returns the pipeline funnel's metrics for the selected opportunities, aggregated (JSON format only) and per-user (JSON and CSV formats).

Every report accepts the following parameters:

* `pipeline`: ID of the pipeline defining the funnel statuses.
* `type`: the type of the report. The available values are `created-cohort` and `active-stage-cohort`.
* `report_relative_range`: a relative time range to fetch data for. The allowed values are: `today`, `this-week`, `this-month`, `this-quarter`, `this-year`, `yesterday`, `last-week`, `last-month`, `last-quarter`, `last-year`, and `all-time`.
* `report_datetime_range`: a time range to fetch data for.
* `cohort_relative_range`: a relative time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. The allowed values are: `today`, `this-week`, `this-month`, `this-quarter`, `this-year`, `yesterday`, `last-week`, `last-month`, `last-quarter`, `last-year`, and `all-time`. Either this field or `cohort_datetime_range` needs to be specified for `created-cohort` reports. Its value will be ignored for `active-stage-cohort` reports.
* `cohort_datetime_range`: a time range defining the cohort of created opportunities to fetch data for, by date of creation of those opportunities. Either this field or `cohort_relative_range` needs to be specified for `created-cohort` reports. Its value will be ignored for `active-stage-cohort` reports.
* `compared_relative_range`: a relative time range to fetch comparison data for. Only allowed in combination with `report_relative_range` (for `active-stage-cohort` reports) or `cohort_relative_range` (for `created-cohort` reports). The allowed values are: `today`, `this-week`, `this-month`, `this-quarter`, `this-year`, `yesterday`, `last-week`, `last-month`, `last-quarter`, `last-year`, and `all-time`.
* `compared_datetime_range`: a relative time range to fetch comparison data for. Only allowed in combination with `report_datetime_range` (for `active-stage-cohort` reports) or `cohort_datetime_range` (for `created-cohort` reports). The allowed values are: `same-days-last-week`, `same-days-last-month`, `same-days-last-quarter`, `same-days-last-year`.
* `compared_custom_range`: a time range to fetch comparison data for.
* `query`: a query to apply to the report to filter out data.
  The value of the field is a dictionary with the key `type` and any type-specific keys. For now only the type `saved_search` is allowed which takes the extra key `saved_search_id` to specify the ID of a saved search. This parameter is *optional*.
* `users`: a list of user IDs or group IDs to limit the report results to. When it's empty, the report will include all the available users. This parameter is *optional*.

The report can be requested either in JSON format or in CSV format. The format can be specified with the `accept` header.

In JSON format, it includes aggregated and per-user data. When requested in CSV format, it includes only per-user data.

When `compared_datetime_range`, `compared_relative_range`, or `compared_custom_range` are used, the report returned is the compared one, not the base one.

Reference: https://developer.close.com/api/resources/reporting/get-funnel-stages

## Authentication

- `Authorization` header (basic auth, required) — Use your API key as the username and leave the password empty.
- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Body (application/json)

This endpoint expects an any.

- `any`

## Response

### 200

Successful response

## Errors

### 400 Bad Request Error

Bad request

- `any`

### 401 Unauthorized Error

Unauthorized

- `any`

### 404 Not Found Error

Not found

- `any`

## Examples

**Request**

```json
{
  "pipeline": "pipe_4vukv2FUlFh9FDiVYAop1U",
  "query": {
    "saved_search_id": "save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239",
    "type": "saved_search"
  },
  "report_datetime_range": {
    "end": "2019-01-08T00:00:00Z",
    "start": "2019-01-01T00:00:00Z"
  },
  "type": "active-stage-cohort",
  "users": [
    "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
    "user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk"
  ]
}
```

**Response**

```json
{
  "aggregations": {
    "stages": [
      {
        "average_time_to_advance": 3600,
        "count": 2,
        "count_conversion_rate": 0.5,
        "count_lost": 1,
        "count_lost_ratio": 0.5,
        "status": {
          "id": "stat_69GagUcJ0k0m4sg8YtLXzC3wiaQpvduPOncBmsyRc5Q",
          "label": "Initial",
          "type": "active"
        },
        "value": 2000000,
        "value_conversion_rate": 0.5,
        "value_lost": 1000000,
        "value_lost_ratio": 0.5,
        "weighted_value": 1000000,
        "weighted_value_conversion_rate": 1
      },
      {
        "average_time_to_advance": null,
        "count": 1,
        "count_conversion_rate": 0,
        "count_lost": 0,
        "count_lost_ratio": 0,
        "status": {
          "id": "stat_6mrcy0uLx1wKGfvhBpwy1UXCzyoD5f2lVGKvBfEI45U",
          "label": "Won",
          "type": "won"
        },
        "value": 1000000,
        "value_conversion_rate": 0,
        "value_lost": 0,
        "value_lost_ratio": 0,
        "weighted_value": 1000000,
        "weighted_value_conversion_rate": 0
      }
    ]
  },
  "data": [
    {
      "stages": [
        {
          "average_time_to_advance": 3600,
          "count": 1,
          "count_conversion_rate": 1,
          "count_lost": 0,
          "count_lost_ratio": 0,
          "status": {
            "id": "stat_69GagUcJ0k0m4sg8YtLXzC3wiaQpvduPOncBmsyRc5Q",
            "label": "Initial",
            "type": "active"
          },
          "value": 1000000,
          "value_conversion_rate": 1,
          "value_lost": 0,
          "value_lost_ratio": 0,
          "weighted_value": 1000000,
          "weighted_value_conversion_rate": 1
        },
        {
          "average_time_to_advance": null,
          "count": 1,
          "count_conversion_rate": 0,
          "count_lost": 0,
          "count_lost_ratio": 0,
          "status": {
            "id": "stat_6mrcy0uLx1wKGfvhBpwy1UXCzyoD5f2lVGKvBfEI45U",
            "label": "Won",
            "type": "won"
          },
          "value": 1000000,
          "value_conversion_rate": 0,
          "value_lost": 0,
          "value_lost_ratio": 0,
          "weighted_value": 1000000,
          "weighted_value_conversion_rate": 0
        }
      ],
      "user_id": "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA"
    },
    {
      "stages": [
        {
          "average_time_to_advance": null,
          "count": 1,
          "count_conversion_rate": 0,
          "count_lost": 1,
          "count_lost_ratio": 1,
          "status": {
            "id": "stat_69GagUcJ0k0m4sg8YtLXzC3wiaQpvduPOncBmsyRc5Q",
            "label": "Initial",
            "type": "active"
          },
          "value": 1000000,
          "value_conversion_rate": 0,
          "value_lost": 1000000,
          "value_lost_ratio": 1,
          "weighted_value": 0,
          "weighted_value_conversion_rate": 0
        },
        {
          "average_time_to_advance": null,
          "count": 0,
          "count_conversion_rate": null,
          "count_lost": 0,
          "count_lost_ratio": null,
          "status": {
            "id": "stat_6mrcy0uLx1wKGfvhBpwy1UXCzyoD5f2lVGKvBfEI45U",
            "label": "Won",
            "type": "won"
          },
          "value": 0,
          "value_conversion_rate": null,
          "value_lost": 0,
          "value_lost_ratio": null,
          "weighted_value": 0,
          "weighted_value_conversion_rate": null
        }
      ],
      "user_id": "user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.close.com/api/v1/report/funnel/opportunity/stages/"

payload = {
    "pipeline": "pipe_4vukv2FUlFh9FDiVYAop1U",
    "query": {
        "saved_search_id": "save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239",
        "type": "saved_search"
    },
    "report_datetime_range": {
        "end": "2019-01-08T00:00:00Z",
        "start": "2019-01-01T00:00:00Z"
    },
    "type": "active-stage-cohort",
    "users": ["user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA", "user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk"]
}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<CLOSE_API_KEY>", ""))

print(response.json())
```

```javascript
const url = 'https://api.close.com/api/v1/report/funnel/opportunity/stages/';
const credentials = btoa("<CLOSE_API_KEY>:");

const options = {
  method: 'POST',
  headers: {Authorization: `Basic ${credentials}`, 'Content-Type': 'application/json'},
  body: '{"pipeline":"pipe_4vukv2FUlFh9FDiVYAop1U","query":{"saved_search_id":"save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239","type":"saved_search"},"report_datetime_range":{"end":"2019-01-08T00:00:00Z","start":"2019-01-01T00:00:00Z"},"type":"active-stage-cohort","users":["user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA","user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.close.com/api/v1/report/funnel/opportunity/stages/"

	payload := strings.NewReader("{\n  \"pipeline\": \"pipe_4vukv2FUlFh9FDiVYAop1U\",\n  \"query\": {\n    \"saved_search_id\": \"save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239\",\n    \"type\": \"saved_search\"\n  },\n  \"report_datetime_range\": {\n    \"end\": \"2019-01-08T00:00:00Z\",\n    \"start\": \"2019-01-01T00:00:00Z\"\n  },\n  \"type\": \"active-stage-cohort\",\n  \"users\": [\n    \"user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA\",\n    \"user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.SetBasicAuth("<CLOSE_API_KEY>", "")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.close.com/api/v1/report/funnel/opportunity/stages/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.basic_auth("<CLOSE_API_KEY>", "")
request["Content-Type"] = 'application/json'
request.body = "{\n  \"pipeline\": \"pipe_4vukv2FUlFh9FDiVYAop1U\",\n  \"query\": {\n    \"saved_search_id\": \"save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239\",\n    \"type\": \"saved_search\"\n  },\n  \"report_datetime_range\": {\n    \"end\": \"2019-01-08T00:00:00Z\",\n    \"start\": \"2019-01-01T00:00:00Z\"\n  },\n  \"type\": \"active-stage-cohort\",\n  \"users\": [\n    \"user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA\",\n    \"user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.close.com/api/v1/report/funnel/opportunity/stages/")
  .basicAuth("<CLOSE_API_KEY>", "")
  .header("Content-Type", "application/json")
  .body("{\n  \"pipeline\": \"pipe_4vukv2FUlFh9FDiVYAop1U\",\n  \"query\": {\n    \"saved_search_id\": \"save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239\",\n    \"type\": \"saved_search\"\n  },\n  \"report_datetime_range\": {\n    \"end\": \"2019-01-08T00:00:00Z\",\n    \"start\": \"2019-01-01T00:00:00Z\"\n  },\n  \"type\": \"active-stage-cohort\",\n  \"users\": [\n    \"user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA\",\n    \"user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.close.com/api/v1/report/funnel/opportunity/stages/', [
  'body' => '{
  "pipeline": "pipe_4vukv2FUlFh9FDiVYAop1U",
  "query": {
    "saved_search_id": "save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239",
    "type": "saved_search"
  },
  "report_datetime_range": {
    "end": "2019-01-08T00:00:00Z",
    "start": "2019-01-01T00:00:00Z"
  },
  "type": "active-stage-cohort",
  "users": [
    "user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA",
    "user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk"
  ]
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<CLOSE_API_KEY>', ''],
]);

echo $response->getBody();
```

```csharp
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://api.close.com/api/v1/report/funnel/opportunity/stages/");
client.Authenticator = new HttpBasicAuthenticator("<CLOSE_API_KEY>", "");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"pipeline\": \"pipe_4vukv2FUlFh9FDiVYAop1U\",\n  \"query\": {\n    \"saved_search_id\": \"save_ZVc26G33JTNiDNEFdZhBQAONg9cJHleAAHqBJakf239\",\n    \"type\": \"saved_search\"\n  },\n  \"report_datetime_range\": {\n    \"end\": \"2019-01-08T00:00:00Z\",\n    \"start\": \"2019-01-01T00:00:00Z\"\n  },\n  \"type\": \"active-stage-cohort\",\n  \"users\": [\n    \"user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA\",\n    \"user_Ova4RGFG7pztSeJiiMFdN7O2MFl71nD0uGO3bIOo4Wk\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```