# Call Reports API ## Reports Parameters `GET https://api.retreaver.com/api/v1/reports.json?....` ### Query Parameters | Parameter | Mandatory | Description | | ---------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | api_key | Yes | The api_key used to authenticate this request. | | company_id | No | Return reports associated to the specific company if you have access to that company. If left blank it defaults to the current company associated with the API key. | | domain | Yes | The domain of the report. Currently only `calls`. | | facet | Yes | One of: `['number', 'campaign', 'affiliate', 'target', 'date', 'tag_value', 'state']`. This is the object that you will want to generate a report for. For companies with the affiliate marketing feature enabled, `publisher` and `buyer` may be used as aliases for `affiliate` and `target` respectively. | | created_at_start | Yes | | | created_at_end | Yes | | | page | No | The page of results to return. Defaults to 1. | | per_page | No | The number of results per page. Defaults to 25, maximum 100. | | tag_value_key | No | When faceting by tag_value you may want to provide a second facet to drill down on. [Example](#tag-value-name-report) | > [!NOTE] > `created_at_start` must be before `created_at_end` and the two must be smaller than 2 years apart. ## Buyer Calls In Progress Report ```shell curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=buyer&domain=calls&created_at_start=2026-04-22&created_at_end=2026-04-24" ``` > The above command returns JSON structured like this: ```json { "count": 2, "count_total": 2, "data": [ { "id": 30417, "facet_name": "Alex Johnson - +14155551234", "total_calls": 5, "in_progress_count": 2.0, "...": "..." }, { "id": 27299, "facet_name": "Power Axle - +16476695972", "total_calls": 3, "in_progress_count": 1.0, "...": "..." } ] } ``` Get a report for all calls faceted by buyer. The `in_progress_count` field indicates how many calls are currently active for each buyer. To get current in-progress calls, set `created_at_start` to today (or yesterday) and `created_at_end` to tomorrow. `GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=buyer&domain=calls&created_at_start=2026-04-22&created_at_end=2026-04-24` | Parameter | Value | | ---------------- | ------------ | | api_key | [api_key] | | company_id | 1 | | domain | calls | | facet | buyer | | created_at_start | 2026-04-22 | | created_at_end | 2026-04-24 | > [!NOTE] > `facet=buyer` is an alias for `facet=target` and only works for companies with the affiliate marketing feature enabled. If your company does not have that feature, use `facet=target` instead. > [!WARNING] > The Reports API response is cached and is not intended for realtime polling. For realtime call tracking, use [webhooks](/guides/webhooks) to receive notifications when calls start, end, convert, and other call lifecycle events. ## Tag Value Report ```shell curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28" ``` > The above command returns JSON structured like this: ```json { "count": 3, "count_total": 3, "data": [ { "id": "utm_campaign", "facet_name": "utm_campaign", "total_calls": 3, "repeat_count": 2.0, "duplicate_count": 0.0, "unique_calls": 1.0, "converted_count": 0.0, "revenue": 0.0, "payout": 0.0, "cost": 0.12, "total_duration": 3.666666666666667, "total_duration_percent": 0.4714045207910327, "rescued_count": 0.0, "rescued_revenue": 0.0, "connected_duration": 0.0, "connected_duration_percent": 0.0, "in_progress_count": 0.0, "profit": -0.12, "repeat_count_percent": 66.66666666666666, "duplicate_count_percent": 0, "converted_count_percent": 0, "rescued_count_percent": 0, "epc": 0, "cpc": 0 } ] } ``` Get a report for all calls between 2024-10-25 and 2024-10-28 faceted by tag_value name. `GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28` | Parameter | Value | | ---------------- | ------------ | | api_key | [api_key] | | company_id | 1 | | domain | calls | | facet | tag_value | | created_at_start | 2024-10-25 | | created_at_end | 2024-10-28 | ## Tag Value Name Report ```shell curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=utm_campaign" ``` > The above command returns JSON structured like this: ```json { "count": 3, "count_total": 3, "data": [ { "id": "ret_campaign_123", "facet_name": "ret_campaign_123", "total_calls": 2, "repeat_count": 2.0, "duplicate_count": 0.0, "unique_calls": 1.0, "converted_count": 0.0, "revenue": 0.0, "payout": 0.0, "cost": 0.12, "total_duration": 3.666666666666667, "total_duration_percent": 0.4714045207910327, "rescued_count": 0.0, "rescued_revenue": 0.0, "connected_duration": 0.0, "connected_duration_percent": 0.0, "in_progress_count": 0.0, "profit": -0.12, "repeat_count_percent": 66.66666666666666, "duplicate_count_percent": 0, "converted_count_percent": 0, "rescued_count_percent": 0, "epc": 0, "cpc": 0 }, { "id": "ret_campaign_456", "facet_name": "ret_campaign_456", "total_calls": 1, "repeat_count": 0, "duplicate_count": 0.0, "unique_calls": 1.0, "converted_count": 0.0, "revenue": 0.0, "payout": 0.0, "cost": 0.12, "total_duration": 3.666666666666667, "total_duration_percent": 0.4714045207910327, "rescued_count": 0.0, "rescued_revenue": 0.0, "connected_duration": 0.0, "connected_duration_percent": 0.0, "in_progress_count": 0.0, "profit": -0.12, "repeat_count_percent": 66.66666666666666, "duplicate_count_percent": 0, "converted_count_percent": 0, "rescued_count_percent": 0, "epc": 0, "cpc": 0 } ] } ``` Get a report for all calls between 2024-10-25 and 2024-10-28 faceted by the tag `utm_campaign`. `GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=utm_campaign` | Parameter | Value | | ---------------- | ------------ | | api_key | [api_key] | | company_id | 1 | | domain | calls | | facet | tag_value | | created_at_start | 2024-10-25 | | created_at_end | 2024-10-28 | | tag_value_key | utm_campaign | ## Not all tag values are indexed ```shell curl "https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=unindexed_tag_value" ``` > The above command returns JSON structured like this: ```json { "count": 0, "count_total": 0, "data": [] } ``` To reduce the noise from billions of uninteresting values, we only report the values for Tags explicitly created for the company along with a few system Tags. To see a report on the values of `unindexed_tag_value`, please visit the Tags page and create a tag with key `unindexed_tag_value`. We will start indexing it from today. Let us know if you would like us to re-index past calls. `GET https://api.retreaver.com/api/v1/reports.json?api_key=[api_key]&company_id=1&facet=tag_value&domain=calls&created_at_start=2024-10-25&created_at_end=2024-10-28&tag_value_key=unindexed_tag_value` | Parameter | Value | | ---------------- | ------------------- | | api_key | [api_key] | | company_id | 1 | | domain | calls | | facet | tag_value | | created_at_start | 2024-10-25 | | created_at_end | 2024-10-28 | | tag_value_key | unindexed_tag_value |