# User and Org Insights API Reference

These APIs can be called from the backend using your PropelAuth API Key. These APIs are used to fetch the raw data used in the [User Insights](https://docs.propelauth.com/overview/user-management/user-insights) reports and charts.

---

GET/api/backend/v1/user/<userId>/signup_query_parameters

## [Fetch User Signup Query Parameters](https://docs.propelauth.com/reference/api/insights#fetch-user-signup-query-parameters)

Fetches the signup query parameters for the user. See the docs [here](https://docs.propelauth.com/overview/user-management/user-insights#user-signup-query-parameters) for more information.

### Required Permissions

Read Users

### Properties

- Name `userId` 
  - Type string
  - Description The ID of the user.

### Request

Javascript

```javascript
auth.fetchUserSignupQueryParams("31c41c16-c281-44ae-9602-8a047e3bf33d");
```

Python

```python
auth.fetch_user_signup_query_params_by_user_id(
    user_id="31c41c16-c281-44ae-9602-8a047e3bf33d",
)
```

Rust

```rust
auth.user().fetch_user_signup_query_parameters(FetchUserSignupQueryParamsParams {
    user_id: "31c41c16-c281-44ae-9602-8a047e3bf33d".to_string(),
})
```

Go

```go
auth.FetchUserSignupQueryParameters(uuid.MustParse("31c41c16-c281-44ae-9602-8a047e3bf33d"))
```

cURL

```bash
curl -H "Authorization: Bearer <API_KEY>" \
    -H "Content-Type: application/json" \
    "<AUTH_URL>/api/backend/v1/user/<userId>/signup_query_parameters"
```

### Successful Response

```json
{
    "user_signup_query_parameters": {
        "query_param_example": "example_value"
    }
}
```

---

GET/api/backend/v1/user_report/top_inviter

## [Fetch User Top Inviter Report](https://docs.propelauth.com/reference/api/insights#fetch-user-top-inviter-report)

Fetches the top inviter report, a leaderboard of users with the highest number of invited users in a period of time.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include '30', '60', and '90' days.
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page.
- Name `pageNumber`
  - Type number
  - Description The page number to return.

### Request

Javascript

```javascript
auth.fetchUserTopInviterReport(
    TopInviterReportInterval.THIRTY_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_user_top_inviter_report(
    report_interval=TopInviterReportInterval.THIRTY_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_user_top_inviter_report(
    TopInviterReportInterval::ThirtyDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchUserTopInviterReport(
    &"30",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/user_report/top_inviter
        ?report_interval=30
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "user_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "user_id": "813bef...",
      "user_created_at": 1701392700,
      "username": "exampleUsername",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acmeinc.com",
      "last_active_at": 1773250562,
      "org_data": [
        {
            "display_name": "Acme Inc",
            "org_id": "4f18c3...",
            "user_role": "Owner"
        }
      ],
      "extra_properties": {
        "numInvites": 4
      }
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/user_report/champion

## [Fetch User Champion Report](https://docs.propelauth.com/reference/api/insights#fetch-user-champion-report)

Fetches the potential champions report, a leaderboard of users with the highest amount of activity in a period of time.

### Required Permissions

Read User Insights Data

### Properties

### Request

Javascript

```javascript
auth.fetchUserChampionReport(
    ChampionReportInterval.THIRTY_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_user_champion_report(
    report_interval=ChampionReportInterval.THIRTY_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_user_champion_report(
    ChampionReportInterval::ThirtyDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchUserChampionReport(
    &"30",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/user_report/champion
        ?report_interval=30
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "user_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "user_id": "813bef...",
      "user_created_at": 1701392700,
      "username": "exampleUsername",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acmeinc.com",
      "last_active_at": 1773250562,
      "org_data": [
        {
          "display_name": "Acme Inc",
          "org_id": "4f18c3...",
          "user_role": "Owner"
        }
      ],
      "extra_properties": {
        "num_active_days": 4
      }
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/user_report/reengagement

## [Fetch User Reengagement Report](https://docs.propelauth.com/reference/api/insights#fetch-user-reengagement-report)

Fetches the reengaged users report, a report of recently active users who were previously inactive for a period of time.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include 'Weekly' and 'Monthly'.
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page.
- Name `pageNumber`
  - Type number
  - Description The page number to return.

### Request

Javascript

```javascript
auth.fetchUserReengagementReport(
    ReengagementReportInterval.WEEKLY,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_user_reengagement_report(
    report_interval=ReengagementReportInterval.WEEKLY,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_user_reengagement_report(
    ReengagementReportInterval::Weekly,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchUserReengagementReport(
    &"Weekly",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/user_report/reengagement
        ?report_interval=Weekly
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "user_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "user_id": "813bef...",
      "user_created_at": 1701392700,
      "username": "exampleUsername",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@acmeinc.com",
      "last_active_at": 1773250562,
      "org_data": [
        {
            "display_name": "Acme Inc",
            "org_id": "4f18c3...",
            "user_role": "Owner"
        }
      ],
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/user_report/churn

## [Fetch User Churn Report](https://docs.propelauth.com/reference/api/insights#fetch-user-churn-report)

Fetches the churned users report, a report of users who have not been active in a certain amount of days.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include '7' and '14', and '30' days.
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page.
- Name `pageNumber`
  - Type number
  - Description The page number to return.

### Request

Javascript

```javascript
auth.fetchUserChurnReport(
    ChurnReportInterval.SEVEN_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_user_churn_report(
    report_interval=ChurnReportInterval.SEVEN_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_user_churn_report(
    ChurnReportInterval::SevenDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchUserChurnReport(
    &"7",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/user_report/churn
        ?report_interval=7
        &page_size=10
        &page_number=0"
```

### Successful Response

---

GET/api/backend/v1/org_report/reengagement

## [Fetch Org Reengagement Report](https://docs.propelauth.com/reference/api/insights#fetch-org-reengagement-report)

Fetches the reengaged org report, a report of organizations with recently active users who had no active users in a period of time.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include 'Weekly' and 'Monthly'
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page
- Name `pageNumber`
  - Type number
  - Description The page number to return

### Request

Javascript

```javascript
auth.fetchOrgReengagementReport(
    ReengagementReportInterval.WEEKLY,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_org_reengagement_report(
    report_interval=ReengagementReportInterval.WEEKLY,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_org_reengagement_report(
    ReengagementReportInterval::Weekly,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchOrgReengagementReport(
    &"Weekly",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/org_report/reengagement
        ?report_interval=Weekly
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "org_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "org_id": "813bef...",
      "name": "Acme Inc",
      "num_users": 1,
      "org_created_at": 1771841702
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/org_report/churn

## [Fetch Org Churn Report](https://docs.propelauth.com/reference/api/insights#fetch-org-churn-report)

Fetches the churned org report, a report of organizations who had no active users in a period of time.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include '7' and '14', and '30' days
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page
- Name `pageNumber`
  - Type number
  - Description The page number to return

### Request

Javascript

```javascript
auth.fetchOrgChurnReport(
    ChurnReportInterval.SEVEN_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_org_churn_report(
    report_interval=ChurnReportInterval.SEVEN_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_org_churn_report(
    ChurnReportInterval::SevenDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchOrgChurnReport(
    &"7",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/org_report/churn
        ?report_interval=7
        &page_size=10
        &page_number=0"
```

### Successful Response

---

GET/api/backend/v1/org_report/growth

## [Fetch Org Growth Report](https://docs.propelauth.com/reference/api/insights#fetch-org-growth-report)

Fetches the org growth report, a leaderboard of the organizations with the highest net growth over a period of time.

### Required Permissions

Read User Insights Data

### Properties

- Name `reportInterval`
  - Type string
  - Description The report interval to return. Options include '30' and '60', and '90' days
- Name `pageSize`
  - Type number
  - Description The number of entries to return per page
- Name `pageNumber`
  - Type number
  - Description The page number to return

### Request

Javascript

```javascript
auth.fetchOrgGrowthReport(
    GrowthReportInterval.THIRTY_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_org_growth_report(
    report_interval=GrowthReportInterval.THIRTY_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_org_growth_report(
    GrowthReportInterval::ThirtyDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchOrgGrowthReport(
    &"30",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/org_report/growth
        ?report_interval=30
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "org_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "org_id": "813bef...",
      "name": "Acme Inc",
      "num_users": 1,
      "org_created_at": 1771841702,
      "extra_properties": {
        "num_users_added": 10,
        "num_users_removed": 3
      }
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/org_report/attrition

## [Fetch Org Attrition Report](https://docs.propelauth.com/reference/api/insights#fetch-org-attrition-report)

Fetches the org attrition report, a leaderboard of the organizations with the highest number of users removed over a period of time.

### Required Permissions

Read User Insights Data

### Properties

### Request

Javascript

```javascript
auth.fetchOrgAttritionReport(
    AttritionReportInterval.THIRTY_DAYS,
    ReportPagination {
        pageSize: 10,
        pageNumber: 0
    }
)
```

Python

```python
auth.fetch_org_attrition_report(
    report_interval=AttritionReportInterval.THIRTY_DAYS,
    page_size=10,
    page_number=0
)
```

Rust

```rust
auth.user_insights().fetch_org_attrition_report(
    AttritionReportInterval::ThirtyDays,
    ReportPagination {
        page_size: Some(10),
        page_number: Some(0),
    }
)
```

Go

```go
auth.FetchOrgAttritionReport(
    &"30",
    &models.ReportPagination {
        PageSize: &10,
        PageNumber: &0,
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/org_report/attrition
        ?report_interval=30
        &page_size=10
        &page_number=0"
```

### Successful Response

```json
{
  "org_reports": [
    {
      "id": "df1940...",
      "report_id": "de58c...",
      "org_id": "813bef...",
      "name": "Acme Inc",
      "num_users": 1,
      "org_created_at": 1771841702,
      "extra_properties": {
        "num_users_added": 10,
        "num_users_removed": 3,
        "net_users_change": 7
      }
    }
  ],
  "current_page": 0,
  "total_count": 2,
  "page_size": 10,
  "has_more_results": false,
  "report_time": 1773330458
}
```

---

GET/api/backend/v1/chart_metric/<chartMetric>

## [Fetch Chart Metric Data](https://docs.propelauth.com/reference/api/insights#fetch-chart-metric-data)

Returns a chart metric report for the given chart metric type and cadence.

### Required Permissions

Read User Insights Data

### Properties

- Name `chartMetric` 
  - Type string
  - Description The type of chart metric to return. Options include 'signups', 'orgs_created', 'active_users', 'active_orgs'
- Name `cadence`
  - Type string
  - Description The cadence of the chart metric to return. Options include 'Daily', 'Weekly', and 'Monthly'
- Name `startDate`
  - Type string
  - Description The start date of the report period
- Name `endDate`
  - Type string
  - Description The end date of the report period

### Request

Javascript

```javascript
auth.fetchChartMetricData(
    ChartMetric.SIGNUPS,
    ChartMetricCadence.DAILY,
    Date("2026-01-01T00:00:00Z"), // start date
    Date("2026-01-31T23:59:59Z"), // end date
)
```

Python

```python
import datetime as dt

auth.fetch_chart_metric_data(
    chart_metric = ChartMetric.SIGNUPS,
    cadence = ChartMetricCadence.DAILY
    start_date = dt.date.fromisoformat('2026-01-01'),
    end_date = dt.date.fromisoformat('2026-01-31'),
)
```

Rust

```rust
auth.user_insights().fetch_chart_metric_data(
    ChartMetric::Signups,
    FetchChartDataQuery {
        cadence: Some(ChartMetricCadence::Daily),
        start_date: Some("2026-01-01".to_string()),
        end_date: Some("2026-01-31".to_string()),
    },
)
```

Go

```go
auth.FetchChartMetricData(
    "signups",
    &"Daily",
    &models.ChartRange {
        StartDate: &"2026-01-01",
        EndDate: &"2026-01-31",
    },
)
```

cURL

```bash
curl -H "Content-Type: application/json" \
      -H "Authorization: Bearer <API_KEY>" \
    "<AUTH_URL>/api/backend/v1/chart_metrics/<chart_metric>
        ?cadence=Daily
        &start_date=2026-01-01
        &end_date=2026-01-31"
```

### Successful Response

```json
{
  "chart_type": "ActiveOrgs",
  "cadence": "Daily",
  "metrics": [
    {
      "date": "2026-01-01",
      "result": 10,
      "cadence_completed": false
    },
    {
      "date": "2026-01-02",
      "result": 14,
      "cadence_completed": false
    }
  ]
}
```