Skip to content
CreatoRainCreatoRain API
Not live yet: the v1 API and its hosts are not open. See Sandbox.

The videos posted from this account's locations, newest first

GET
/videos
curl --request GET \
  --url 'https://api.creatorain.com/v1/videos?limit=50' \
  --header 'Authorization: Bearer <token>'

Scope read. Live videos only. A video is this account’s when it is stated at one of its locations, or, stated at none, linked to a visit at one, or its creator was booked at one. counted_on_bill is true only for a video stated at its location: those are what the month’s pace and the bill count, so the list can hold videos not counted on the bill. stats is null until the public post was first read. Creators appear by public handle only.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
location
string
/^loc_[0-9a-f]{32}$/

Only this location’s items. Another account’s location is 404 not_found (field location).

cursor
string
<= 512 characters

The next_cursor of the previous page, unchanged. Omit it for the first page. Anything else is 400 parameter_invalid (field cursor).

limit
integer
default: 50 >= 1 <= 200

Items a page, 1 to 200.

Responses

Section titled “Responses”

200

Section titled “200”

One page of videos.

Media typeapplication/json
object
object
required
string
Allowed values: list
data
required
Array<object>
object
object
required
string
Allowed values: video
id
required
string
livemode
required
boolean
location_id
required
string
visit_id
required

The visit this video is linked to, at the same location; else null.

string
nullable
platform
required
string
nullable
url
required
string format: uri
nullable
published_at
required

On the store’s offset.

string format: date-time
nullable
timezone
required
string
nullable
status
required
string
Allowed values: live
counted_on_bill
required

Stated at its location, so counted by the month’s pace and the bill. A linked or booked-creator video is listed with false.

boolean
creator
required
object
handle
required
string
nullable
is_collab
required

The store’s account is a co-author of the public post.

boolean
stats
required

Null until the public post was first read.

object
views
required
integer
nullable
likes
required
integer
nullable
comments
required
integer
nullable
measured_at
required
object
views
required
string format: date-time
nullable
likes
required
string format: date-time
nullable
comments
required
string format: date-time
nullable
next_cursor
required
string
nullable

Example 

{
  "object": "list",
  "data": [
    {
      "object": "video",
      "id": "vid_3f2a9c1e5b7d4a6f8e0c2b4d6f8a0c2e",
      "platform": "tiktok",
      "status": "live"
    }
  ]
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

RateLimit-Limit
integer
Example 
600

Requests allowed in the current minute for this workspace (600).

RateLimit-Remaining
integer

Requests left in the current minute for this workspace.

RateLimit-Reset
integer

Seconds until the current window resets.

400

Section titled “400”

Parameter_invalid (with field) or invalid_json.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

401

Section titled “401”

Invalid_key, test_key_on_live or live_key_on_sandbox.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

403

Section titled “403”

Scope_missing or forbidden_ip.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

404

Section titled “404”

Not_found.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

429

Section titled “429”

Rate_limited (600 a minute per workspace, an onboarding create limit, or an address blocked after failed authentication), or slow_down (an onboarding session polled too fast).

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

Retry-After
integer
>= 1

Seconds to wait before retrying (at least 1).

500

Section titled “500”

Internal_error (500) or service_unavailable (503). The message never carries a cause.

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.

503

Section titled “503”

Service_unavailable. The read is unavailable right now (for the bill preview, an account over 2000 locations).

Media typeapplication/json
object
error
required
object
type
required
string
Allowed values: invalid_request_error authentication_error permission_error idempotency_error rate_limit_error api_error
code
required
string
Allowed values: parameter_invalid invalid_json idempotency_key_invalid idempotency_key_required customization_not_supported videos_per_month_out_of_range batch_invalid terms_not_accepted invalid_key test_key_on_live live_key_on_sandbox insufficient_balance scope_missing forbidden_ip forbidden live_key_requires_top_up limit_raise_requires_dashboard not_found idempotency_conflict idempotency_in_progress conflict location_already_in_network external_id_conflict dispute_open request_too_large address_not_verified not_food_business metro_not_served package_not_available account_location_limit commit_limit_exceeded top_up_exceeds_feasible no_saved_card rate_limited quota_exceeded slow_down internal_error service_unavailable
message
required
string
field

The request field at fault

string
doc_url
required
string format: uri
request_id
required
string format: uuid
items

Batch_invalid only. Every refused location, by its index in the request.

Array<object>
object
index
required
integer
code
required

One of the error codes above.

string
field
string
message
required
string

Example 

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "doc_url": "https://www.creatorain.com/api/errors#scope_missing",
    "items": [
      {
        "field": "locations.1.videos_per_month"
      }
    ]
  }
}

Headers

Section titled “Headers”
Request-Id
string format: uuid

This request’s id. Equal to error.request_id; quote it to support.