Ingest a Creator On Demand

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"
    }
  }
}

Creators

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 200 with status: already_exists at no charge
For a new creator, you get 202 with status: ingesting as 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 instagram handles
Each account has a daily ingest quota; exceeding it returns 429 with quota_exceeded and a Retry-After header
Handles that do not exist return 404 and are not charged
If the handle cannot be validated right now you get 503 with service_unavailable; retry shortly
The daily ingest quota is only consumed when a request is accepted. 404, 422, and 503 outcomes 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.

POST

creators

ingest

Ingest a Creator On Demand

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

X-API-Key

string

header

required

Body

application/json

On-demand creator ingest request

platform

enum<string>

required

Platform of the handle to ingest. Use instagram.

Available options:

instagram

Example:

"instagram"

username

string

required

Handle to ingest. A leading @ is stripped and the handle is lowercased before validation.

Required string length: 1 - 50

Example:

"fitness_coach_jane"

source_query

string

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.

Maximum string length: 500

Example:

"vegan fitness coaches in Austin"

Response

Successful response

data

object

required

On-demand creator ingest result

Show child attributes

Overview

Endpoints

Ingest a Creator On Demand

Authorizations

Body

Response