curl --request POST \
--url https://api.influship.com/v1/creators/ingest \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"platform": "instagram",
"username": "fitness_coach_jane",
"source_query": "vegan fitness coaches in Austin"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
platform: 'instagram',
username: 'fitness_coach_jane',
source_query: 'vegan fitness coaches in Austin'
})
};
fetch('https://api.influship.com/v1/creators/ingest', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.influship.com/v1/creators/ingest"
payload = {
"platform": "instagram",
"username": "fitness_coach_jane",
"source_query": "vegan fitness coaches in Austin"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"status": "ingesting",
"creator": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "fitness_coach_jane",
"platform": "instagram"
},
"status_url": "/v1/creators/123e4567-e89b-12d3-a456-426614174000"
}
}{
"data": {
"status": "ingesting",
"creator": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "fitness_coach_jane",
"platform": "instagram"
},
"status_url": "/v1/creators/123e4567-e89b-12d3-a456-426614174000"
}
}{
"error": {
"code": "validation_error",
"message": "Invalid value for parameter 'limit': must be between 1 and 100",
"param": "limit",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "unauthorized",
"message": "API key missing or invalid",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "payment_required",
"message": "Payment authentication is required.",
"status_code": 402,
"reason_code": "PAYMENT_ACTION_REQUIRED",
"next_step": "complete_authentication",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "not_found",
"message": "Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "validation_error",
"message": "Invalid Instagram username format",
"param": "username",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded (per minute)",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "service_unavailable",
"message": "Live Instagram data is temporarily unavailable. Please retry shortly.",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"details": {
"retry_after_seconds": 60,
"upstream_error": "upstream_rate_limited"
}
}
}Ingest a Creator On Demand
Add a public Instagram creator by handle for discovery and campaign research. The API checks the handle, then enriches new profiles asynchronously.
How it works:
- The handle is normalized and validated live to confirm it exists
- For an existing creator, you get
200withstatus: already_existsat no charge - For a new creator, you get
202withstatus: ingestingas enrichment begins
Polling for results:
Poll the returned status_url (GET /v1/creators/{id}) with an attempt limit and a deadline. Profile details and creator analysis become available at different times. While enrichment is in progress, that endpoint can return 404 or incomplete fields. See on-demand ingestion for a bounded polling example.
Limits:
- Submit
instagramhandles - Each account has a daily ingest quota; exceeding it returns
429withquota_exceededand aRetry-Afterheader - Handles that do not exist return
404and are not charged - If the handle cannot be validated right now you get
503withservice_unavailable; retry shortly - The daily ingest quota is only consumed when a request is accepted.
404,422, and503outcomes do not use a slot
Pricing: 5 credits per creator ingested ($0.05). Charged when a new creator is accepted for enrichment. Existing, not-found, and invalid handles are free.
curl --request POST \
--url https://api.influship.com/v1/creators/ingest \
--header 'Content-Type: application/json' \
--header 'X-API-Key: <api-key>' \
--data '
{
"platform": "instagram",
"username": "fitness_coach_jane",
"source_query": "vegan fitness coaches in Austin"
}
'const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
platform: 'instagram',
username: 'fitness_coach_jane',
source_query: 'vegan fitness coaches in Austin'
})
};
fetch('https://api.influship.com/v1/creators/ingest', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.influship.com/v1/creators/ingest"
payload = {
"platform": "instagram",
"username": "fitness_coach_jane",
"source_query": "vegan fitness coaches in Austin"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"data": {
"status": "ingesting",
"creator": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "fitness_coach_jane",
"platform": "instagram"
},
"status_url": "/v1/creators/123e4567-e89b-12d3-a456-426614174000"
}
}{
"data": {
"status": "ingesting",
"creator": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"username": "fitness_coach_jane",
"platform": "instagram"
},
"status_url": "/v1/creators/123e4567-e89b-12d3-a456-426614174000"
}
}{
"error": {
"code": "validation_error",
"message": "Invalid value for parameter 'limit': must be between 1 and 100",
"param": "limit",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "unauthorized",
"message": "API key missing or invalid",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "payment_required",
"message": "Payment authentication is required.",
"status_code": 402,
"reason_code": "PAYMENT_ACTION_REQUIRED",
"next_step": "complete_authentication",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "not_found",
"message": "Creator with ID '123e4567-e89b-12d3-a456-426614174000' not found",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "validation_error",
"message": "Invalid Instagram username format",
"param": "username",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded (per minute)",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"error": {
"code": "service_unavailable",
"message": "Live Instagram data is temporarily unavailable. Please retry shortly.",
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"details": {
"retry_after_seconds": 60,
"upstream_error": "upstream_rate_limited"
}
}
}Authorizations
Body
On-demand creator ingest request
On-demand creator ingest request
Platform of the handle to ingest. Use instagram.
instagram "instagram"
Handle to ingest. A leading @ is stripped and the handle is lowercased before validation.
1 - 50"fitness_coach_jane"
Optional free-text note describing why this creator is being ingested (e.g. the search that surfaced them). Stored for your own attribution; does not affect processing.
500"vegan fitness coaches in Austin"
Response
Successful response
On-demand creator ingest result
Show child attributes
Show child attributes