Profiles API

The Profiles API lets you query the semantic profiles that Cipres builds for each user. Every message processed through the Users API is analyzed and folded into a cumulative profile — tracking sentiment trends, topic affinities, churn risk, and intentions over time. Use this API to read those profiles, filter by behavioral patterns, and access individual message timelines.

List Profiles

GET https://cipres.tech/api/v1/profiles

Returns a paginated list of user profiles for a project. Supports filters for churn risk, sentiment trend, and minimum message count — useful for finding at-risk users or identifying behavioral cohorts programmatically.

Headers

Request Headers
X-API-Key required
string

Your API key for authentication.

Query Parameters

Query Parameters
project_id required
integer

The project to query profiles from.

limit
integer

Maximum number of profiles to return. Default: 20, max: 100.

offset
integer

Number of profiles to skip for pagination. Default: 0.

churn_risk_gte
float

Filter users with churn_risk_score >= this value (0.0 to 1.0).

churn_risk_lte
float

Filter users with churn_risk_score <= this value (0.0 to 1.0).

sentiment_trend
string

Filter by sentiment trend. Values: "improving", "stable", "declining".

min_messages
integer

Only return users with at least this many analyzed messages.

Example Request

List all profiles 
curl https://cipres.tech/api/v1/profiles?project_id=1&limit=20 \
  -H "X-API-Key: sk_a1b2c3d4..."
Filter by churn risk and sentiment 
# Users with high churn risk and declining sentiment
curl "https://cipres.tech/api/v1/profiles?project_id=1\
  &churn_risk_gte=0.7\
  &sentiment_trend=declining\
  &min_messages=3" \
  -H "X-API-Key: sk_a1b2c3d4..."

Responses

{
  "users": [
    {
      "user_id": "user_123",
      "source_label": "SaaS Feedback",
      "attributes": {
        "plan": "pro",
        "country": "US"
      },
      "aggregates": {
        "window_size": 10,
        "avg_sentiment": -0.42,
        "sentiment_trend": "declining",
        "top_topics": ["billing", "support", "pricing"],
        "topic_scores": {
          "billing": 0.85,
          "support": 0.62,
          "pricing": 0.41
        },
        "intentions_summary": ["wants refund", "considering alternatives"],
        "negative_ratio": 0.7,
        "churn_risk_score": 0.78,
        "price_sensitive_ratio": 0.5,
        "message_frequency_days": 3.2
      },
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-02-01T14:22:00Z"
    }
  ],
  "total": 1
}

Get Profile

GET https://cipres.tech/api/v1/profiles/:user_id

Returns the full profile for a single user, including their attributes, all aggregate metrics, and metadata.

Headers

Request Headers
X-API-Key required
string

Your API key for authentication.

Query Parameters

Query Parameters
project_id required
integer

The project the user belongs to.

Example Request

cURL 
curl https://cipres.tech/api/v1/profiles/user_123?project_id=1 \
  -H "X-API-Key: sk_a1b2c3d4..."

Responses

{
  "user_id": "user_123",
  "source_label": "SaaS Feedback",
  "attributes": {
    "plan": "pro",
    "country": "US"
  },
  "aggregates": {
    "window_size": 10,
    "avg_sentiment": -0.42,
    "sentiment_trend": "declining",
    "top_topics": ["billing", "support", "pricing"],
    "topic_scores": {
      "billing": 0.85,
      "support": 0.62,
      "pricing": 0.41
    },
    "intentions_summary": ["wants refund", "considering alternatives"],
    "negative_ratio": 0.7,
    "churn_risk_score": 0.78,
    "price_sensitive_ratio": 0.5,
    "message_frequency_days": 3.2
  },
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-02-01T14:22:00Z"
}

Get User Timeline

GET https://cipres.tech/api/v1/profiles/:user_id/timeline

Returns the chronological list of analyzed messages for a user. Each entry includes the extracted sentiment, topics, and intentions from that specific message. Useful for understanding how a user's behavior has evolved.

Headers

Request Headers
X-API-Key required
string

Your API key for authentication.

Query Parameters

Query Parameters
project_id required
integer

The project the user belongs to.

Example Request

cURL 
curl https://cipres.tech/api/v1/profiles/user_123/timeline?project_id=1 \
  -H "X-API-Key: sk_a1b2c3d4..."

Responses

{
  "user_id": "user_123",
  "timeline": [
    {
      "timestamp": "2025-02-01T14:22:00Z",
      "source_label": "SaaS Feedback",
      "sentiment": -0.8,
      "topics": ["billing", "pricing"],
      "intentions": ["wants refund"]
    },
    {
      "timestamp": "2025-01-28T09:15:00Z",
      "source_label": "SaaS Feedback",
      "sentiment": -0.3,
      "topics": ["support"],
      "intentions": ["needs help"]
    },
    {
      "timestamp": "2025-01-20T16:45:00Z",
      "source_label": "SaaS Feedback",
      "sentiment": 0.2,
      "topics": ["onboarding"],
      "intentions": []
    }
  ]
}

Profile Fields Reference

Each user profile includes an aggregates object with the following fields. These are recalculated every time a new message is processed for the user.

Aggregate Fields
window_size
integer

Number of messages included in the aggregation window.

avg_sentiment
float

Average sentiment score across recent messages (-1.0 to 1.0).

sentiment_trend
string

Direction of sentiment over time: "improving", "stable", or "declining".

top_topics
string[]

Most frequent topics across the user's messages, ranked by score.

topic_scores
object

Topic frequency scores (0.0 to 1.0) for each detected topic.

intentions_summary
string[]

Aggregated user intentions detected across all messages.

negative_ratio
float

Proportion of messages with negative sentiment (0.0 to 1.0).

churn_risk_score
float

Multi-factor churn risk score (0.0 to 1.0). Combines negative sentiment, declining trends, and churn-related intentions.

price_sensitive_ratio
float

Proportion of messages expressing price sensitivity (0.0 to 1.0).

message_frequency_days
float

Average number of days between messages from this user.

Use Cases

  • Churn prevention — Query profiles with churn_risk_gte=0.7 to find users at risk and trigger outreach
  • Sentiment monitoring — Filter by sentiment_trend=declining to catch users whose experience is degrading
  • Behavioral cohorts — Combine filters to build dynamic lists: high-risk users who write frequently, or loyal users with positive trends
  • User timeline analysis — Use the timeline endpoint to understand the progression of a specific user's experience over time
  • CRM enrichment — Pull profile data into your CRM to give sales and support teams context on each user's semantic history