Why is the first question slower than the ones after it?

Because nobody has looked at the video yet. The first question is the one that watches it, and how long that takes follows the length of the video. Every question after it reads what the first look wrote down, so it comes back far quicker.

How long does a session last?

As long as the video is stored for your plan. A session is a handle on one video, not a connection, so nothing times out while you are not using it. Keep the id beside whatever you are building and use it days later.

Does a follow-up cost credits?

Yes, and far fewer. A follow-up does not watch the video again, so you pay for reading notes rather than for a reading. Every answer says what it charged in credits_charged, and the same question asked twice costs nothing the second time.

Can two people share one session?

Anybody in your organization can. A session_id from another organization is refused, because a session belongs to whoever paid to watch that video.

Sessions

The first question about a video is the one that watches it. Every question after it carries the session_id that came back, and reads what the first look already found instead of watching again. That is why it is quicker and costs a fraction. The shape to plan for is one wide look, then as many narrow questions as your job needs.

Last updated 31 August 2026

The shape

One wide look, then as many narrow questions as your job needs. That is the shape to plan for, and it is the whole of what a session is.

The first question, and the session it hands backbash

# The first question watches the video. Keep what comes back.
SESSION=$(curl -sX POST https://api.tryplayhead.com/v1/watch_video \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@user/video/730…"}' | jq -r .session_id)

# Every question after it carries the session, and is short.
curl -sX POST https://api.tryplayhead.com/v1/watch_video \
  -H "Authorization: Bearer $PLAYHEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"session_id\":\"$SESSION\",\"question\":\"what does the price say\"}" \
  | jq -r .answer

The same applies from an agent. watch_video answers with a session_id line, and passing it back is the difference between a few hundred tokens and a few thousand.

What it costs

A first look is quoted by the length of the video. A follow-up costs a fraction of it, because it does not open the video again.

What a first look is quoted at
The video is	A first look is quoted at
up to 1 minute	1,100 credits
up to 10 minutes	11,000 credits
up to 1 hour	65,000 credits
longer	130,000 credits

The first band is also the floor, so a fifteen second advert is quoted the same 1,100 credits as a full minute. These are estimates you can read before you call. What you are charged is what the work cost, and the answer says so in credits_charged. The same question asked twice costs nothing the second time. Pricing has the rate in dollars.

What a session holds

Everything that was read about one video, and where each thing was read.

The first question watches the video and writes down what it found: what is on screen, what is said, who is in it, and the second of each. A later question reads those notes. When the notes do not answer it, that question looks again, at the seconds it needs and no more.

Watching again

A video that changed, or an answer you do not believe.

Ask us to watch it again and the answer states the price rather than starting the work. Ask again with rewatch set and it runs: a new reading, charged as a new first look. Nothing is deleted, so the earlier answer stays readable.

What a second look answers before it runsjson

{
  "answer": "Watching this video again costs 11,000 credits. Ask again with `rewatch` set to start it.",
  "credits_charged": 0
}

Questions

Why is the first question slower than the ones after it?: Because nobody has looked at the video yet. The first question is the one that watches it, and how long that takes follows the length of the video. Every question after it reads what the first look wrote down, so it comes back far quicker.
How long does a session last?: As long as the video is stored for your plan. A session is a handle on one video, not a connection, so nothing times out while you are not using it. Keep the id beside whatever you are building and use it days later.
Does a follow-up cost credits?: Yes, and far fewer. A follow-up does not watch the video again, so you pay for reading notes rather than for a reading. Every answer says what it charged in credits_charged, and the same question asked twice costs nothing the second time.
Can two people share one session?: Anybody in your organization can. A session_id from another organization is refused, because a session belongs to whoever paid to watch that video.