Authentication
Authenticate requests with your API key using the following HTTP header.
Authorization: Bearer <YOUR_KEY>API access requires a paid workspace. Calls are billed by usage.
GET/api/openapi/v1/reports/<JOB_ID>Retrieve status and result
API pricingFree
Supported platformsInstagram / YouTube / TikTok / Twitter / X
Quick start (cURL)
curl 'https://app.hicreator.ai/api/openapi/v1/reports/<JOB_ID>?type=audience_analysis' \ -H 'Authorization: Bearer <YOUR_KEY>'
Poll every 5 seconds while queued or running; stop when finished.
Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string (UUID) | Yes | data.id returned on submission. |
| type | string | Yes | data.type returned on submission.View allowed valuesaudience_analysis / fake_follower_check |
result is returned on success; null means no result yet.
Response fields
| Parameter | Type | Always returned | Description |
|---|---|---|---|
| requestId | string | Yes | Request ID for support. |
| data | object | Yes | Task and report. |
| data.id | string (UUID) | Yes | Report task ID. |
| data.type | string | Yes | Report type.View allowed valuesaudience_analysis / fake_follower_check |
| data.platform | string | null | Yes | Platform. |
| data.canonicalUrl | string | null | Yes | Creator profile link. |
| data.status | string | Yes | Task status.View allowed valuesqueued / running / succeeded / unavailable / failed |
| data.errorCode | string | null | Yes | Failure code. |
| data.createdAt | string | Yes | Created at. |
| data.startedAt | string | null | Yes | Started at. |
| data.finishedAt | string | null | Yes | Finished at. |
| data.result | object | null | Yes | Report result. |
| data.result.countries | object[] | Yes | Country or region distribution. |
| data.result.ageRanges | object[] | Yes | Age distribution. |
| data.result.genders | object[] | Yes | Gender distribution. |
| data.result.countries[].key | string | Yes | Country or region code, e.g. US. |
| data.result.countries[].share | number | Yes | Audience share from 0 to 1. |
| data.result.ageRanges[].key | string | Yes | Age range.View allowed values13-17 / 18-34 / 35-64 / 65+ |
| data.result.ageRanges[].share | number | Yes | Audience share from 0 to 1. |
| data.result.genders[].key | string | Yes | Gender.View allowed valuesmale / female |
| data.result.genders[].share | number | Yes | Audience share from 0 to 1. |
Example response (JSON)
{
"requestId": "<http-request-id>",
"data": {
"id": "11111111-1111-4111-8111-111111111111",
"platform": "twitter",
"canonicalUrl": "https://x.com/example_creator",
"status": "succeeded",
"errorCode": null,
"createdAt": "2026-10-08T01:00:00.000Z",
"startedAt": "2026-10-08T01:00:00.000Z",
"finishedAt": "2026-10-08T01:02:00.000Z",
"type": "audience_analysis",
"result": {
"countries": [
{
"key": "US",
"share": 0.7
},
{
"key": "GB",
"share": 0.3
}
],
"ageRanges": [
{
"key": "18-34",
"share": 0.8
},
{
"key": "35-64",
"share": 0.2
}
],
"genders": [
{
"key": "female",
"share": 0.6
},
{
"key": "male",
"share": 0.4
}
]
}
}
}Errors and retries
See error.message; keep requestId for support. Do not retry uncertain requests.
See data.errorCode if the task fails.