> ## Documentation Index > Fetch the complete documentation index at: https://docs.eversince.ai/llms.txt > Use this file to discover all available pages before exploring further. # pull posts > One page of what a platform is publishing, stored nowhere: each post's words, dates, handle or advertiser, engagement, permalink, and every picture and video at the source's address, which expires within days. inspect_media urls looks at them, and with a prompt has a model answer about one; transcribe_media takes them too. keep_posts keeps chosen posts within two days. source plus an account or a query; next_cursor is the page after, and the same ask again returns the same page. A post already kept carries its ref. The answer names the account it reached. Credits, a fraction of one a page. ## OpenAPI ````yaml /openapi.json post /tools/pull_posts openapi: 3.1.0 info: title: Eversince API version: '1' description: >- Every Eversince tool as one POST call, plus the routes beside them: the tool list, account and keys, uploads, webhooks and models. The prose is at https://docs.eversince.ai. servers: - url: https://eversince.ai/api/v1 security: - bearer: [] tags: - name: Discovery description: The tool list, the same on the MCP server, the REST API and the CLI. - name: Workspace description: Jobs, balances, settings, templates, skills and the overview. - name: Library description: >- Items, search, import, reading media, comments, boards, calendars, the brand kit and public links. - name: Timeline description: 'Video editing: timelines, clips, captions, sound, language and rendering.' - name: Canvas description: 'Still editing: canvases, slides, layers and rendering.' - name: Generation description: Image, video and audio generation, upscaling, cutouts and models. - name: Research description: 'What platforms publish: pulling and keeping posts.' - name: Account description: Balances, keys, workspaces and script sessions. - name: Uploads description: Files into the library by presigned upload or by URL. - name: Webhooks description: Job results posted to a URL as they complete. - name: Models description: Generation models and cost estimates. paths: /tools/pull_posts: post: tags: - Research summary: pull posts description: >- One page of what a platform is publishing, stored nowhere: each post's words, dates, handle or advertiser, engagement, permalink, and every picture and video at the source's address, which expires within days. inspect_media urls looks at them, and with a prompt has a model answer about one; transcribe_media takes them too. keep_posts keeps chosen posts within two days. source plus an account or a query; next_cursor is the page after, and the same ask again returns the same page. A post already kept carries its ref. The answer names the account it reached. Credits, a fraction of one a page. operationId: pull_posts parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/WorkspaceId' requestBody: required: true content: application/json: schema: type: object properties: source: type: string enum: - meta_ads - tiktok_ads - linkedin_ads - tiktok - instagram - youtube - reddit description: >- Where to pull from. meta_ads, tiktok_ads and linkedin_ads are ad libraries and carry ad creative and copy; tiktok, instagram, youtube and reddit are organic. account: description: >- A profile link, an @handle, or a name. tiktok, instagram and youtube: a link or handle pulls that account; a name is searched on tiktok, refused on instagram, read as keywords on youtube. meta_ads: an Ad Library link or a name it resolves; tiktok_ads and linkedin_ads: a name; reddit: keywords. This or query. type: string query: description: Keywords, for a niche rather than a named account. type: string cursor: description: >- The next_cursor a previous pull returned, for the page after it. Each page is its own call and its own charge. Absent from the sources that page nothing: instagram by query, youtube by query. type: string market: description: >- 2-letter market, e.g. "US". meta_ads, tiktok_ads and linkedin_ads only; the organic sources have no market parameter and answer globally. type: string status: description: >- meta_ads only, active by default. "inactive" is what a brand has stopped running. type: string enum: - active - inactive - all since: description: >- YYYY-MM-DD. meta_ads (the impressions window) and linkedin_ads (the run window) only. type: string until: description: YYYY-MM-DD. meta_ads and linkedin_ads only. type: string order: description: >- The source's own ordering. meta_ads: total_impressions (default) or relevancy_monthly_grouped. tiktok_ads: for_you, impression, play_2s_rate, play_6s_rate, cvr, ctr, like. tiktok and youtube by account: latest, popular. tiktok by query: relevance, most-liked, date-posted. reddit: relevance, new, top, comment_count. youtube by query: relevance, popular. Others have none; an unknown value is dropped. type: string posted: description: >- How far back, in the source's terms. tiktok by query: yesterday, this-week, this-month, last-3-months, last-6-months, all-time. instagram by query: last-hour, last-day, last-week, last-month, last-year. youtube by query: today, this_week, this_month, this_year, any. reddit: day, week, month, year, all. Ad libraries use since and until. type: string match: description: >- meta_ads with a query: exact_phrase for a multi-word product or brand name that must match whole. type: string enum: - keyword_unordered - keyword_exact_phrase language: description: >- 2-letter ad language, e.g. "EN". meta_ads by account and tiktok_ads only, and it narrows a market pull to one language. type: string industry: description: >- tiktok_ads only: a Creative Center category, named however you like; it is resolved to the platform's own taxonomy key, and dropped when nothing matches. type: string objective: description: 'tiktok_ads only: the campaign objective.' type: string enum: - app_installs - conversions - lead_generation - product_sales - reach - traffic - video_views duration: description: >- How long the piece runs, in the source's buckets. tiktok_ads: under_10s, 10_20s, 20_30s, 30_40s, 40_50s, over_50s. youtube by query: under_3_min, between_3_and_20_min, over_20_min. type: string likes: description: >- tiktok_ads only: the likes percentile band, top_1_20 being the best-performing. type: string enum: - top_1_20 - top_21_40 - top_41_60 - top_61_80 - top_81_100 ad_format: description: tiktok_ads only. type: string enum: - spark_ads - non_spark_ads period: description: 'tiktok_ads only: the top-ads window in days.' anyOf: - type: number const: 7 - type: number const: 30 - type: number const: 180 content_type: description: >- youtube by query only: shorts isolates short-form. Omit for both. type: string enum: - videos - shorts context: description: 'Optional: one sentence shown to the user beside this action.' type: string maxLength: 600 required: - source responses: '200': description: >- Done, or a job started for work that runs longer (follow it with get_jobs). content: application/json: schema: type: object required: - ok - data - meta properties: ok: const: true data: type: object additionalProperties: true meta: type: object properties: request_id: type: string cost: $ref: '#/components/schemas/Cost' cloud_processing: $ref: '#/components/schemas/CloudProcessing' media: type: array items: type: object additionalProperties: true default: $ref: '#/components/responses/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false schema: type: string description: >- Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again. WorkspaceId: name: x-workspace-id in: header required: false schema: type: string description: The workspace this one call acts in, when it is not the key's own. schemas: Cost: type: object description: AI credits the call cost. additionalProperties: true CloudProcessing: type: object description: Cloud processing the call used, and what is left. properties: ran_on: const: cloud minutes: type: number queued_minutes: type: number left_minutes: type: number bought_minutes: type: number note: type: string Error: type: object required: - ok - error properties: ok: const: false error: type: object required: - code - message - retryable properties: code: type: string message: type: string description: What went wrong, in words to act on. retryable: type: boolean suggested_action: type: string description: The next step that works. cloud_processing: $ref: '#/components/schemas/CloudProcessing' responses: Error: description: The call was refused or failed. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearer: type: http scheme: bearer description: >- An API key (es_live_…) from Settings, under API keys, or an OAuth access token. ````