> ## Documentation Index > Fetch the complete documentation index at: https://docs.clipstake.com/llms.txt > Use this file to discover all available pages before exploring further. # Put posts under tracking ## OpenAPI ````yaml /openapi.json post /instagram/submissions openapi: 3.1.0 info: title: Clipstake API description: >- Instagram, X and YouTube media tracking, audience geography and demographics, as an API. version: 0.0.1 servers: - url: https://api.clipstake.com/v1 security: [] paths: /instagram/submissions: post: tags: - Submissions summary: Put posts under tracking operationId: instagram-submissions-create parameters: [] requestBody: required: true content: application/json: schema: type: object properties: project_id: type: string account_id: type: string pattern: ^acct_[0-9a-f]{24}$ items: minItems: 1 maxItems: 100 type: array items: type: object properties: url: type: string maxLength: 2048 format: uri metadata: type: object propertyNames: type: string minLength: 1 maxLength: 40 additionalProperties: type: string maxLength: 500 required: - url cadence_hours: type: number enum: - 1 - 2 - 3 - 4 - 6 - 8 - 12 description: >- How often to read each media, in hours: 1, 2, 3, 4, 6, 8 or 12. A faster cadence costs fewer credits per read and more per day. The default is the project's cadence. start_at: description: >- When tracking starts. The first read is at this time. The default is now. type: string format: date-time end_at: description: >- When tracking ends. It must be after start_at and in the future. type: string format: date-time geo: description: >- Collect audience data. Instagram and YouTube only. If you leave it out, the project's default applies. New projects default to on. On Instagram, geo reads the account's audience. Each read costs 4 more credits, and the account costs 1,500 credits per day. On YouTube, geo reads the media's own audience. Each read costs 4 more credits, with no account cost. We charge the 4 credits only while there is audience data to report. type: boolean required: - project_id - account_id - items responses: '200': description: Successful response content: application/json: schema: type: object properties: estimate: type: object properties: credits_per_read: type: integer minimum: -9007199254740991 maximum: 9007199254740991 reads_per_day: type: integer minimum: -9007199254740991 maximum: 9007199254740991 credits_per_day: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- For one media. The daily geo account fee is not included. geo_account_credits_per_day: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: >- Charged once per day for each Instagram account with a geo media. 0 when geo is off, and always 0 on YouTube. required: - credits_per_read - reads_per_day - credits_per_day - geo_account_credits_per_day additionalProperties: false description: What one media with these settings costs. data: type: array items: type: object properties: url: type: string status: type: string description: >- Known values: created, already_tracked, not_found, unsupported_url, platform_mismatch, not_owned (X and YouTube: another account published this URL), not_video (X: the URL has no video; YouTube: the URL is a live or upcoming broadcast). submission: anyOf: - type: object properties: id: type: string pattern: ^sub_[0-9a-f]{24}$ platform: type: string description: >- Platform identifier. Known values: instagram, x, youtube. url: type: string format: uri platform_media_id: type: string media_type: description: >- Known values: short_video, video, image, carousel, text. On YouTube, short_video means 180 seconds or less and video means longer than 180 seconds. type: - string - 'null' account: type: object properties: id: type: string pattern: ^acct_[0-9a-f]{24}$ username: type: string external_user_id: type: string required: - id - username - external_user_id additionalProperties: false posted_at: anyOf: - type: string format: date-time - type: 'null' status: type: string enum: - active - paused - unavailable - parked - stopped next_read_at: anyOf: - type: string format: date-time - type: 'null' unavailable_reason: description: >- Known values: post_not_found, posted_before_professional, token_invalid, no_linked_account, connection_removed. type: - string - 'null' parked_reason: description: >- Known values: token_invalid, insights_permission_missing, account_not_professional, read_failed. type: - string - 'null' latest: type: object properties: captured_at: anyOf: - type: string format: date-time - type: 'null' views: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' reach: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' likes: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' comments: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' shares: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' saves: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' total_interactions: anyOf: - type: integer minimum: -9007199254740991 maximum: 9007199254740991 - type: 'null' extra: type: object propertyNames: type: string additionalProperties: type: number required: - captured_at - views - reach - likes - comments - shares - saves - total_interactions - extra additionalProperties: false metadata: type: object propertyNames: type: string minLength: 1 maxLength: 40 additionalProperties: type: string maxLength: 500 cadence_hours: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: How often this media is read, in hours. start_at: anyOf: - type: string format: date-time - type: 'null' description: >- When tracking starts. Null means it started at create. end_at: anyOf: - type: string format: date-time - type: 'null' description: >- When tracking ends. The media becomes stopped at this time. Null means no end date. geo: type: boolean description: >- True when audience data is collected for this media: its account's audience on Instagram, the media's own audience on YouTube. Instagram and YouTube only. created_at: type: string format: date-time required: - id - platform - url - platform_media_id - media_type - account - posted_at - status - next_read_at - unavailable_reason - parked_reason - metadata - cadence_hours - start_at - end_at - geo - created_at additionalProperties: false - type: 'null' required: - url - status - submission additionalProperties: false required: - estimate - data additionalProperties: false example: estimate: credits_per_read: 15 reads_per_day: 6 credits_per_day: 90 geo_account_credits_per_day: 1500 data: - url: https://www.instagram.com/p/C9x4AbCdEfG/ status: created submission: id: sub_4f9c0a1b2c3d4e5f60718293 platform: instagram url: https://www.instagram.com/p/C9x4AbCdEfG/ platform_media_id: '18062712345678901' media_type: short_video account: id: acct_3f9c0a1b2c3d4e5f60718293 username: acme.studio external_user_id: customer_8f3a2c19 posted_at: '2026-09-10T14:22:00.000Z' status: active next_read_at: '2026-09-14T14:00:00.000Z' unavailable_reason: null parked_reason: null latest: captured_at: '2026-09-14T10:00:00.000Z' views: 128450 reach: 96720 likes: 8140 comments: 326 shares: 1190 saves: 2480 total_interactions: 12136 extra: {} metadata: campaign: fall cadence_hours: 4 start_at: null end_at: '2026-10-10T14:25:43.000Z' geo: true created_at: '2026-09-10T14:25:43.000Z' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/error.BAD_REQUEST' example: error: code: invalid_request message: The request body or parameters are invalid. request_id: req_01K5A7N8QY2M4C6V9X3J '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/error.UNAUTHORIZED' example: error: code: unauthorized message: Provide a valid API key. request_id: req_01K5A7P2CH8T6R4W9M1B '402': description: Payment required content: application/json: schema: $ref: '#/components/schemas/error.PAYMENT_REQUIRED' example: error: code: insufficient_credits message: >- This workspace has no credits left. Buy credits on the Billing page to resume tracking. balance: 0 required: 1 request_id: req_01K5A7P8VM2T6R4W9C3H '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/error.NOT_FOUND' example: error: code: not_found message: The requested resource was not found. request_id: req_01K5A7R4WM9C2N6B8X3D '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/error.CONFLICT' example: error: code: conflict message: Submission discovery is already running. request_id: req_01K5A7T3MX8C2V6B9N4P '429': description: Too many requests content: application/json: schema: $ref: '#/components/schemas/error.TOO_MANY_REQUESTS' example: error: code: rate_limited message: The platform is rate-limiting this account. request_id: req_01K5A7S2JT5B9W3M7R1F '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR' example: error: code: internal_error message: An unexpected error occurred. request_id: req_01K5A7S6FQ3V8H2N9C4M security: - Authorization: [] components: schemas: error.BAD_REQUEST: type: object properties: message: type: string description: The error message example: Bad request code: type: string description: The error code example: BAD_REQUEST issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Bad request error (400) description: The error information example: code: BAD_REQUEST message: Bad request issues: [] error.UNAUTHORIZED: type: object properties: message: type: string description: The error message example: Unauthorized code: type: string description: The error code example: UNAUTHORIZED issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Unauthorized error (401) description: The error information example: code: UNAUTHORIZED message: Unauthorized issues: [] error.PAYMENT_REQUIRED: type: object properties: message: type: string description: The error message example: Payment required code: type: string description: The error code example: PAYMENT_REQUIRED issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Payment required error (402) description: The error information example: code: PAYMENT_REQUIRED message: Payment required issues: [] error.NOT_FOUND: type: object properties: message: type: string description: The error message example: Not found code: type: string description: The error code example: NOT_FOUND issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Not found error (404) description: The error information example: code: NOT_FOUND message: Not found issues: [] error.CONFLICT: type: object properties: message: type: string description: The error message example: Conflict code: type: string description: The error code example: CONFLICT issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Conflict error (409) description: The error information example: code: CONFLICT message: Conflict issues: [] error.TOO_MANY_REQUESTS: type: object properties: message: type: string description: The error message example: Too many requests code: type: string description: The error code example: TOO_MANY_REQUESTS issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Too many requests error (429) description: The error information example: code: TOO_MANY_REQUESTS message: Too many requests issues: [] error.INTERNAL_SERVER_ERROR: type: object properties: message: type: string description: The error message example: Internal server error code: type: string description: The error code example: INTERNAL_SERVER_ERROR issues: description: An array of issues that were responsible for the error example: [] type: array items: type: object properties: message: type: string required: - message additionalProperties: false required: - message - code additionalProperties: false title: Internal server error error (500) description: The error information example: code: INTERNAL_SERVER_ERROR message: Internal server error issues: [] securitySchemes: Authorization: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.