Docs menu
Referrals API endpoint
List referral attributions
Lists referral attributions with their reward records for support and operational review.
/admin/referralsOverview
Lists referral attributions with their reward records for support and operational review.
Request schema
| Name | In | Type | Required | Enum | Example | Description |
|---|---|---|---|---|---|---|
| x-api-key | header | string | Yes | Admin API key | ||
| user_id | query | string | No | Filter by referrer or referred user id | ||
| status | query | string | No | attributed, qualified, review_required, rewarded, expired, capped, failed, rejected | Filter by attribution status | |
| campaign | query | string | No | Filter by UTM campaign | ||
| pending_grant | query | boolean | No | Only attributions with pending reward grants | ||
| limit | query | integer | No | Maximum records to return, capped at 100 |
Authentication
Admin endpoints require an Admin JWT through the console proxy or an Admin API key where documented. Non-admin plans receive 403.
Billing
Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.
- Credit cost
- 1 credit/request
- Charged response
- Successful 2xx responses
| Plan | Price | Included credits | Daily cap | Rate limit | Overage |
|---|---|---|---|---|---|
| Free | $0/mo | 2,000 | 500 daily credits | 5/min | No overage |
| Starter | $9/mo | 20,000 | 5,000 daily credits | 15/min | $0.75/1,000 overage credits when enabled |
| Growth | $29/mo | 100,000 | 25,000 daily credits | 45/min | $0.45/1,000 overage credits when enabled |
| Pro | $79/mo | 400,000 | No daily cap | 120/min | $0.30/1,000 overage credits |
| Business | $199/mo | 1,200,000 | No daily cap | 300/min | $0.20/1,000 overage credits |
| Enterprise | $499/mo | 5,000,000 | No daily cap | 1,000/min | $0.12/1,000 overage credits |
Infrastructure behavior
This endpoint is executed through Crawlora's managed scraping infrastructure.
- Proxy strategy: managed automatically where needed
- Browser rendering: enabled for supported targets that require rendered HTML or JavaScript execution
- Browser cluster: supported dynamic workloads can be routed through distributed browser instances
- Retry behavior: automatic retry/fallback may be used depending on endpoint type
- Challenge handling: challenged pages or unusable upstream HTML are detected and surfaced clearly when they cannot be used
- Billing: credits are charged only for successful 2xx responses
- Observability: responses include request context where available
Response behavior
- Returns attribution records with raw user ids for Admin review. - Includes reward records for each attribution so pending or failed credit grants are visible. - Does not mutate referral state.
Error behavior
Crawlora does not silently return bad data when the upstream page cannot be used.
| Status | Common failure case |
|---|---|
| 400 | Invalid input or missing required parameter |
| 429 | Plan or endpoint rate limit exceeded |
| 500 | Internal execution error |
| 502 | Upstream platform failed, returned unusable HTML, or served a challenge page that could not be resolved |
When possible, Crawlora returns structured error context so your integration can retry, back off, or inspect the request.
Failure responses
| Status | Description | Schema |
|---|---|---|
| 401 | Authentication required | #/definitions/app.Response |
| 403 | Admin plan required | #/definitions/app.Response |
| 500 | Internal server error | #/definitions/app.Response |
Example response
{
"code": 200,
"msg": "ok",
"data": {
"items": [
{
"attribution": {
"id": "attr-1",
"code": "A1B2C3D4E5F6",
"referrer_user_id": "user-referrer",
"referred_user_id": "user-referred",
"status": "rewarded"
},
"rewards": [
{
"id": "reward-1",
"role": "referrer",
"credits": 10000
}
]
}
]
}
}Request schema
No body schema
Response schema
#/definitions/referrals.adminReferralsListResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| items | array | No | ||||
| items[].attribution | referrals.adminReferralAttributionRecordDoc | No | ||||
| items[].attribution.click_id | string | No | refclk_abc123 | |||
| items[].attribution.code | string | No | A1B2C3D4E5F6 | |||
| items[].attribution.created_at | string | No | ||||
| items[].attribution.error | string | No | temporary billing write failure | |||
| items[].attribution.expires_at | string | No | ||||
| items[].attribution.first_paid_invoice_id | string | No | in_123 | |||
| items[].attribution.id | string | No | attr-1 | |||
| items[].attribution.landing_path | string | No | /pricing | |||
| items[].attribution.qualified_at | string | No | ||||
| items[].attribution.referred_user_id | string | No | user-referred | |||
| items[].attribution.referrer_user_id | string | No | user-referrer | |||
| items[].attribution.review_reason | string | No | same_stripe_customer | |||
| items[].attribution.reviewed_at | string | No | ||||
| items[].attribution.reviewed_by | string | No | admin-user | |||
| items[].attribution.rewarded_at | string | No | ||||
| items[].attribution.risk_flags | array | No | same_stripe_customer | |||
| items[].attribution.skip_reason | string | No | capped | |||
| items[].attribution.status | string | No | attributed, qualified, review_required, rewarded, expired, capped, failed, rejected | rewarded | ||
| items[].attribution.stripe_event_id | string | No | evt_123 | |||
| items[].attribution.stripe_invoice_id | string | No | in_123 | |||
| items[].attribution.utm_campaign | string | No | spring-launch | |||
| items[].attribution.utm_medium | string | No | ||||
| items[].attribution.utm_source | string | No | newsletter | |||
| items[].rewards | array | No | ||||
| items[].rewards[].attribution_id | string | No | attr-1 | |||
| items[].rewards[].created_at | string | No | ||||
| items[].rewards[].credits | integer | No | 10000 | |||
| items[].rewards[].credits_grant_error | string | No | temporary billing write failure | |||
| items[].rewards[].credits_grant_key | string | No | reward-1 | |||
| items[].rewards[].credits_granted_at | string | No | ||||
| items[].rewards[].id | string | No | reward-1 | |||
| items[].rewards[].role | string | No | referrer, referred | referrer | ||
| items[].rewards[].stripe_invoice_id | string | No | in_123 | |||
| items[].rewards[].user_id | string | No | user-referrer |
Code examples
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/admin/referrals?status=attributed&pending_grant=true&limit=10" \
-H "x-api-key: $CRAWLORA_API_KEY"Responsible public web data workflows
Crawlora is designed for responsible structured public web data workflows. Customers are responsible for using Crawlora in compliance with applicable laws, third-party rights, target-platform rules, and Crawlora terms.
Read Crawlora terms